@fedify/relay 2.0.0-dev.109 → 2.0.0-dev.150

package/README.md

@@ -102,7 +102,7 @@ import { MemoryKvStore } from "@fedify/fedify";
 // Create a Mastodon-style relay
 const relay = createRelay("mastodon", {
   kv: new MemoryKvStore(),
-  domain: "relay.example.com",
+  origin: "https://relay.example.com",
   // Required: Set a subscription handler to approve/reject subscriptions
   subscriptionHandler: async (ctx, actor) => {
     // For an open relay, simply return true
@@ -124,7 +124,7 @@ You can also create a LitePub-style relay by changing the type:
 ~~~~ typescript
 const relay = createRelay("litepub", {
   kv: new MemoryKvStore(),
-  domain: "relay.example.com",
+  origin: "https://relay.example.com",
   subscriptionHandler: async (ctx, actor) => true,
 });
 ~~~~
@@ -137,7 +137,7 @@ subscription requests.  For an open relay that accepts all subscriptions:
 ~~~~ typescript
 const relay = createRelay("mastodon", {
   kv: new MemoryKvStore(),
-  domain: "relay.example.com",
+  origin: "https://relay.example.com",
   subscriptionHandler: async (ctx, actor) => true,  // Accept all
 });
 ~~~~
@@ -147,7 +147,7 @@ You can also implement custom approval logic:
 ~~~~ typescript
 const relay = createRelay("mastodon", {
   kv: new MemoryKvStore(),
-  domain: "relay.example.com",
+  origin: "https://relay.example.com",
   subscriptionHandler: async (ctx, actor) => {
     // Example: Only allow subscriptions from specific domains
     const domain = new URL(actor.id!).hostname;
@@ -200,7 +200,7 @@ import { MemoryKvStore } from "@fedify/fedify";
 const app = new Hono();
 const relay = createRelay("mastodon", {
   kv: new MemoryKvStore(),
-  domain: "relay.example.com",
+  origin: "https://relay.example.com",
   subscriptionHandler: async (ctx, actor) => true,
 });
 
@@ -284,6 +284,8 @@ Public interface for ActivityPub relay implementations.
     followers of the relay
  -  `getFollower(actorId: string): Promise<RelayFollower | null>`: Gets
     a specific follower by actor ID
+ -  `getActorUri(): Promise<URL>`: Gets the URI of the relay actor
+ -  `getSharedInboxUri(): Promise<URL>`: Gets the shared inbox URI of the relay
 
 #### Relay types
 
@@ -299,7 +301,8 @@ The relay type is specified when calling `createRelay()`:
 Configuration options for the relay:
 
  -  `kv: KvStore` (required): Key–value store for persisting relay data
- -  `domain?: string`: Relay's domain name (defaults to `"localhost"`)
+ -  `origin: string` (required): Relay's origin URL (e.g.,
+    `"https://relay.example.com"`)
  -  `name?: string`: Relay's display name (defaults to `"ActivityPub Relay"`)
  -  `subscriptionHandler: SubscriptionRequestHandler` (required): Handler for
     subscription approval/rejection

package/dist/mod.cjs

@@ -140,11 +140,7 @@ var BaseRelay = class {
 		this.federationBuilder = relayBuilder$1;
 	}
 	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 });
+		return await (await this.#getFederation()).fetch(request, { contextData: this.options });
 	}
 	/**
 	* Helper method to parse and validate follower data from storage.
@@ -177,7 +173,7 @@ var BaseRelay = class {
 	*
 	* const relay = createRelay("mastodon", {
 	*   kv: new MemoryKvStore(),
-	*   domain: "relay.example.com",
+	*   origin: "https://relay.example.com",
 	*   subscriptionHandler: async (ctx, actor) => true,
 	* });
 	*
@@ -211,7 +207,7 @@ var BaseRelay = class {
 	*
 	* const relay = createRelay("mastodon", {
 	*   kv: new MemoryKvStore(),
-	*   domain: "relay.example.com",
+	*   origin: "https://relay.example.com",
 	*   subscriptionHandler: async (ctx, actor) => true,
 	* });
 	*
@@ -230,6 +226,25 @@ var BaseRelay = class {
 		const followerData = await this.options.kv.get(["follower", actorId]);
 		return await this.parseFollowerData(actorId, followerData);
 	}
+	async #getFederation() {
+		if (this.federation == null) {
+			this.federation = await this.federationBuilder.build(this.options);
+			this.setupInboxListeners();
+		}
+		return this.federation;
+	}
+	async #createContext() {
+		const context = (await this.#getFederation()).createContext(new URL(this.options.origin), this.options);
+		return context;
+	}
+	async getActorUri() {
+		const context = await this.#createContext();
+		return context.getActorUri(RELAY_SERVER_ACTOR);
+	}
+	async getSharedInboxUri() {
+		const context = await this.#createContext();
+		return context.getInboxUri();
+	}
 };
 
 //#endregion
@@ -419,7 +434,7 @@ var MastodonRelay = class extends BaseRelay {
 *
 * const relay = createRelay("mastodon", {
 *   kv: new MemoryKvStore(),
-*   domain: "relay.example.com",
+*   origin: "https://relay.example.com",
 *   subscriptionHandler: async (ctx, actor) => true,
 * });
 * ```

package/dist/mod.d.cts

@@ -16,12 +16,41 @@ type SubscriptionRequestHandler = (ctx: Context<RelayOptions>, clientActor: Acto
  * 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;
+  /**
+   * 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;
 }
 /**
@@ -73,6 +102,18 @@ interface Relay {
    * @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.
@@ -98,7 +139,7 @@ interface Relay {
  *
  * const relay = createRelay("mastodon", {
  *   kv: new MemoryKvStore(),
- *   domain: "relay.example.com",
+ *   origin: "https://relay.example.com",
  *   subscriptionHandler: async (ctx, actor) => true,
  * });
  * ```

package/dist/mod.d.ts

@@ -17,12 +17,41 @@ type SubscriptionRequestHandler = (ctx: Context<RelayOptions>, clientActor: Acto
  * 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;
+  /**
+   * 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;
 }
 /**
@@ -74,6 +103,18 @@ interface Relay {
    * @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.
@@ -99,7 +140,7 @@ interface Relay {
  *
  * const relay = createRelay("mastodon", {
  *   kv: new MemoryKvStore(),
- *   domain: "relay.example.com",
+ *   origin: "https://relay.example.com",
  *   subscriptionHandler: async (ctx, actor) => true,
  * });
  * ```

package/dist/mod.js

@@ -117,11 +117,7 @@ var BaseRelay = class {
 		this.federationBuilder = relayBuilder$1;
 	}
 	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 });
+		return await (await this.#getFederation()).fetch(request, { contextData: this.options });
 	}
 	/**
 	* Helper method to parse and validate follower data from storage.
@@ -154,7 +150,7 @@ var BaseRelay = class {
 	*
 	* const relay = createRelay("mastodon", {
 	*   kv: new MemoryKvStore(),
-	*   domain: "relay.example.com",
+	*   origin: "https://relay.example.com",
 	*   subscriptionHandler: async (ctx, actor) => true,
 	* });
 	*
@@ -188,7 +184,7 @@ var BaseRelay = class {
 	*
 	* const relay = createRelay("mastodon", {
 	*   kv: new MemoryKvStore(),
-	*   domain: "relay.example.com",
+	*   origin: "https://relay.example.com",
 	*   subscriptionHandler: async (ctx, actor) => true,
 	* });
 	*
@@ -207,6 +203,25 @@ var BaseRelay = class {
 		const followerData = await this.options.kv.get(["follower", actorId]);
 		return await this.parseFollowerData(actorId, followerData);
 	}
+	async #getFederation() {
+		if (this.federation == null) {
+			this.federation = await this.federationBuilder.build(this.options);
+			this.setupInboxListeners();
+		}
+		return this.federation;
+	}
+	async #createContext() {
+		const context = (await this.#getFederation()).createContext(new URL(this.options.origin), this.options);
+		return context;
+	}
+	async getActorUri() {
+		const context = await this.#createContext();
+		return context.getActorUri(RELAY_SERVER_ACTOR);
+	}
+	async getSharedInboxUri() {
+		const context = await this.#createContext();
+		return context.getInboxUri();
+	}
 };
 
 //#endregion
@@ -396,7 +411,7 @@ var MastodonRelay = class extends BaseRelay {
 *
 * const relay = createRelay("mastodon", {
 *   kv: new MemoryKvStore(),
-*   domain: "relay.example.com",
+*   origin: "https://relay.example.com",
 *   subscriptionHandler: async (ctx, actor) => true,
 * });
 * ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/relay",
-  "version": "2.0.0-dev.109+ecc823d2",
+  "version": "2.0.0-dev.150+7daa59dd",
   "description": "ActivityPub relay support for Fedify",
   "keywords": [
     "Fedify",
@@ -52,13 +52,13 @@
     "@logtape/logtape": "^1.3.5"
   },
   "peerDependencies": {
-    "@fedify/fedify": "^2.0.0-dev.109+ecc823d2"
+    "@fedify/fedify": "^2.0.0-dev.150+7daa59dd"
   },
   "devDependencies": {
     "tsdown": "^0.12.9",
     "typescript": "^5.9.3",
-    "@fedify/testing": "^2.0.0-dev.109+ecc823d2",
-    "@fedify/vocab-runtime": "^2.0.0-dev.109+ecc823d2"
+    "@fedify/vocab-runtime": "^2.0.0-dev.150+7daa59dd",
+    "@fedify/testing": "^2.0.0-dev.150+7daa59dd"
   },
   "scripts": {
     "build": "deno task codegen && tsdown",