Republish bot profile updates

Add Session.republishProfile() so bots can broadcast an ActivityPub
Update for their current actor profile to followers.

The staged changes also add regression coverage for the new session
API, update the session and bot concept docs, and record the feature
in CHANGES.md.

Closes #18

Author: dahlia

CHANGES.md

@@ -44,8 +44,17 @@ To be released.
         automatically redirects to the appropriate follow page using the OStatus
         subscribe protocol.
 
+ -  Added `Session.republishProfile()` to broadcast profile changes to
+    followers.  [[#18]]
+
+     -  The new method sends an ActivityPub `Update` activity for the bot
+        actor to the bot's followers.
+     -  This makes profile updates such as display name, bio, avatar, and
+        header image propagate without waiting for the next post.
+
 [#10]: https://github.com/fedify-dev/botkit/issues/10
 [#14]: https://github.com/fedify-dev/botkit/pull/14
+[#18]: https://github.com/fedify-dev/botkit/issues/18
 
 
 Version 0.3.1

docs/concepts/bot.md

@@ -126,6 +126,10 @@ The type of the bot actor.  It can be either `Application` or `Service`.
 The display name of the bot.  It can be changed after the bot is
 federated.
 
+If you change it after deployment and want followers to notice the change
+immediately, call
+[`Session.republishProfile()`](./session.md#republishing-the-bot-profile).
+
 ### `~CreateBotOptions.summary`
 
 The description of the bot.  It will be displayed in the bio field
@@ -134,6 +138,10 @@ of the profile.  It can be changed after the bot is federated.
 Note that it does not take a string, but a `Text` object.
 See also the [*Text* chapter](./text.md).
 
+If you change it after deployment and want followers to notice the change
+immediately, call
+[`Session.republishProfile()`](./session.md#republishing-the-bot-profile).
+
 ### `~CreateBotOptions.icon`
 
 The avatar URL of the bot.  It can be changed after the bot is federated.
@@ -144,6 +152,10 @@ The avatar URL of the bot.  It can be changed after the bot is federated.
 > the avatar image so that it looks fine on the most fediverse platforms,
 > you need to change the image file itself.
 
+If you change it after deployment and want followers to notice the change
+immediately, call
+[`Session.republishProfile()`](./session.md#republishing-the-bot-profile).
+
 ### `~CreateBotOptions.image`
 
 The header image URL of the bot.  It can be changed after the bot is federated.
@@ -154,6 +166,10 @@ The header image URL of the bot.  It can be changed after the bot is federated.
 > the header image so that it looks fine on the most fediverse platforms,
 > you need to change the image file itself.
 
+If you change it after deployment and want followers to notice the change
+immediately, call
+[`Session.republishProfile()`](./session.md#republishing-the-bot-profile).
+
 ### `~CreateBotOptions.properties`
 
 The custom properties of the bot. Usually you would like to put some metadata

docs/concepts/session.md

@@ -131,6 +131,26 @@ const actor: Actor = await session.getActor();
 ~~~~
 
 
+Republishing the bot profile
+----------------------------
+
+If you change the bot's profile metadata, such as the display name, bio,
+avatar, or header image, remote servers may keep showing the old cached
+profile until they refresh it themselves.  You can explicitly notify your
+followers by calling the `~Session.republishProfile()` method:
+
+~~~~ typescript twoslash
+import type { Session } from "@fedify/botkit";
+const session = {} as unknown as Session<void>;
+// ---cut-before---
+await session.republishProfile();
+~~~~
+
+This sends an ActivityPub `Update` activity for the bot actor to the bot's
+followers.  Call it after your application updates the bot profile and you want
+the change to propagate without waiting for the next post.
+
+
 Publishing a message
 --------------------
 

packages/botkit/src/session-impl.test.ts

@@ -24,6 +24,7 @@ import {
   Question,
   type Recipient,
   Undo,
+  Update,
 } from "@fedify/vocab";
 import assert from "node:assert";
 import { describe, test } from "node:test";
@@ -264,6 +265,43 @@ describe("SessionImpl.follows()", () => {
   });
 });
 
+test("SessionImpl.republishProfile()", async () => {
+  const bot = new BotImpl<void>({
+    kv: new MemoryKvStore(),
+    username: "bot",
+    name: "Bot display name",
+    summary: text`This is the bot profile.`,
+    icon: new URL("https://example.com/icon.png"),
+    image: new URL("https://example.com/header.png"),
+  });
+  const ctx = createMockContext(bot, "https://example.com");
+  const session = new SessionImpl(bot, ctx);
+
+  await session.republishProfile();
+
+  assert.deepStrictEqual(ctx.sentActivities.length, 1);
+  const { recipients, activity } = ctx.sentActivities[0];
+  assert.deepStrictEqual(recipients, "followers");
+  assert.ok(activity instanceof Update);
+  assert.deepStrictEqual(activity.actorId, ctx.getActorUri(bot.identifier));
+  assert.deepStrictEqual(activity.toIds, [ctx.getFollowersUri(bot.identifier)]);
+  assert.deepStrictEqual(activity.ccIds, []);
+  const actor = await activity.getObject(ctx);
+  assert.ok(actor instanceof bot.class);
+  assert.deepStrictEqual(actor.id, session.actorId);
+  assert.deepStrictEqual(actor.name?.toString(), "Bot display name");
+  assert.deepStrictEqual(
+    actor.summary?.toString(),
+    "<p>This is the bot profile.</p>",
+  );
+  const icon = await actor.getIcon();
+  assert.ok(icon != null);
+  assert.deepStrictEqual(icon.url, new URL("https://example.com/icon.png"));
+  const image = await actor.getImage();
+  assert.ok(image != null);
+  assert.deepStrictEqual(image.url, new URL("https://example.com/header.png"));
+});
+
 test("SessionImpl.publish()", async (t) => {
   const kv = new MemoryKvStore();
   const bot = new BotImpl<void>({ kv, username: "bot" });

packages/botkit/src/session-impl.ts

@@ -27,6 +27,7 @@ import {
   type Object,
   PUBLIC_COLLECTION,
   Undo,
+  Update,
 } from "@fedify/vocab";
 import { getLogger } from "@logtape/logtape";
 import { encode } from "html-entities";
@@ -213,6 +214,25 @@ export class SessionImpl<TContextData> implements Session<TContextData> {
     return follow != null;
   }
 
+  async republishProfile(): Promise<void> {
+    const actor = await this.getActor();
+    const update = new Update({
+      id: new URL(`#update-profile/${crypto.randomUUID()}`, this.actorId),
+      actor: this.actorId,
+      to: this.context.getFollowersUri(this.bot.identifier),
+      object: actor,
+    });
+    await this.context.sendActivity(
+      this.bot,
+      "followers",
+      update,
+      {
+        preferSharedInbox: true,
+        excludeBaseUris: [new URL(this.context.origin)],
+      },
+    );
+  }
+
   async publish(
     content: Text<"block", TContextData>,
     options?: SessionImplPublishOptions<TContextData>,

packages/botkit/src/session.ts

@@ -104,6 +104,18 @@ export interface Session<TContextData> {
    */
   follows(actor: Actor | URL | string): Promise<boolean>;
 
+  /**
+   * Republishes the bot profile to its followers.
+   *
+   * This is useful when the bot's profile metadata such as its display name,
+   * bio, avatar, or header image has changed and remote servers need to be
+   * notified explicitly.
+   *
+   * @returns A promise that resolves when the profile update activity is sent.
+   * @since 0.4.0
+   */
+  republishProfile(): Promise<void>;
+
   /**
    * Publishes a message attributed to the bot.
    * @param text The content of the note.

packages/botkit/src/text.test.ts

@@ -145,6 +145,9 @@ const bot: BotWithVoidContextData = {
       publish() {
         throw new Error("Not implemented");
       },
+      republishProfile() {
+        throw new Error("Not implemented");
+      },
       getOutbox() {
         throw new Error("Not implemented");
       },