feat: add actor mute/unmute

Author: pirhoo

docs/guide/features.md

@@ -11,14 +11,14 @@ Trotsky is currently limited to the following features:
  **StepActorFollowings** | :white_check_mark: | Get an actor's followings | ```Trotsky.init(agent).actor('bsky.app').followings().each()``` 
  **StepActorLikes** | :white_check_mark: | Get an actor's likes. | ```Trotsky.init(agent).actor('bsky.app').likes().each()``` 
  **StepActorLists** | :white_check_mark: | Get an actor's lists. | ```Trotsky.init(agent).actor('bsky.app').lists().each()``` 
- **StepActorMute** | :x: | Mute an actor. |  
+ **StepActorMute** | :white_check_mark: | Mute an actor. | ```Trotsky.init(agent).actor('bsky.app').mute()```  
  **StepActorPosts** | :white_check_mark: | Get an actor's posts | ```Trotsky.init(agent).actor('bsky.app').posts().each()``` 
  **StepActors** | :white_check_mark: | Get a list of actors by their DIDs or handles. | ```Trotsky.init(agent).actors(['bsky.app', 'trotsky.pirhoo.com']).each()``` 
  **StepActorStarterPacks** | :x: | Get an actor starter packs. | 
  **StepActorStreamPosts** | :test_tube: | Stream an actor's posts. | ```Trotsky.init(agent).actor('bsky.app').streamPosts().each()``` 
  **StepActorUnblock** | :white_check_mark: | Unblock an actor. | ```Trotsky.init(agent).actor('bsky.app').unblock()``` 
  **StepActorUnfollow** | :white_check_mark: | Unfollow an actor. | ```Trotsky.init(agent).actor('bsky.app').unfollow()``` 
- **StepActorUnmute** | :x: | Unmute an actor. |  
+ **StepActorUnmute** | :white_check_mark: | Unmute an actor. | ```Trotsky.init(agent).actor('bsky.app').unmute()```  
  **StepCreatePost** | :white_check_mark: | Create a post. | ```Trotsky.init(agent).post({ text: "Mapo Tofu is spicy 🌶️" })``` 
  **StepList** | :white_check_mark: | Get a list by its URI. | ```Trotsky.init(agent).list("at://did:plc:4cs4fudwvazeed2f4b6zjkj5/app.bsky.graph.list/3lbmn7qvjfr2m")``` 
  **StepListMembers** | :white_check_mark: | Get a list's members. | ```Trotsky.init(agent).list("at://did:plc:4cs4fudwvazeed2f4b6zjkj5/app.bsky.graph.list/3lbmn7qvjfr2m").members().each()``` 

lib/core/StepActorMute.ts

@@ -0,0 +1,26 @@
+import { Step, type StepActor, type StepActorOutput } from "../trotsky"
+
+/**
+ * Represents a step that performs an actor mute operation using the Bluesky API.
+ * @typeParam P - Type of the parent step, extending {@link StepActor}.
+ * @typeParam C - Type of the context object, extending {@link StepActorOutput}.
+ * @typeParam O - Type of the output object.
+ * @public
+ */
+export class StepActorMute<P = StepActor, C extends StepActorOutput = StepActorOutput, O = null> extends Step<P, C, O> {
+
+  /**
+   * Applies the step by performing a mute operation.
+   * Requires the context to provide the `did` of the actor to mute.
+   * @throws Error
+   * if no context is found.
+   */
+  async apply () {
+    if (!this.context) {
+      throw new Error("No context found for StepActorMute")
+    }
+
+    const actor = this.context.did
+    await this.agent.mute(actor)
+  }
+}

lib/core/StepActorUnmute.ts

@@ -0,0 +1,27 @@
+import { Step, type StepActor, type StepActorOutput } from "../trotsky"
+
+/**
+ * Represents step that unmutes the current actor (if muted).
+ *
+ * @typeParam P - The parent step type, defaulting to {@link StepActor}.
+ * @typeParam C - The context or child output type, defaulting to {@link StepActorOutput}.
+ * @typeParam O - The output type produced by this step, defaulting to `null`.
+ * @public
+ */
+export class StepActorUnmute<P = StepActor, C extends StepActorOutput = StepActorOutput, O = null> extends Step<P, C, O> {
+
+  /**
+   * Applies the unmute logic by calling the unmute API endpoint.
+   *
+   * @throws Error
+   * If no context is available for the step, indicating the actor is unknown.
+   */
+  async apply () {
+    if (!this.context) {
+      throw new Error("No context found for StepActorUnmute")
+    }
+
+    const actor = this.context.did
+    await this.agent.unmute(actor)
+  }
+}

lib/core/mixins/ActorMixins.ts

@@ -1,14 +1,16 @@
 import {
-  Step, 
-  StepActorBlock, 
-  StepActorFollow, 
-  StepActorFollowers, 
-  StepActorFollowings, 
+  Step,
+  StepActorBlock,
+  StepActorFollow,
+  StepActorFollowers,
+  StepActorFollowings,
   StepActorLists,
-  StepActorLikes, 
-  StepActorPosts, 
-  StepActorUnblock, 
+  StepActorLikes,
+  StepActorMute,
+  StepActorPosts,
+  StepActorUnblock,
   StepActorUnfollow,
+  StepActorUnmute,
   StepActorStreamPosts
 } from "../../trotsky"
 
@@ -111,11 +113,31 @@ export abstract class ActorMixins<P, C, O> extends Step<P, C, O> {
 
   /**
    * Appends a step to unfollow the current actor.
-   * 
+   *
    * @returns The current instance for method chaining.
    */
   unfollow () {
     this.append(StepActorUnfollow<this>)
     return this
   }
+
+  /**
+   * Appends a step to mute the current actor.
+   *
+   * @returns The current instance for method chaining.
+   */
+  mute () {
+    this.append(StepActorMute<this>)
+    return this
+  }
+
+  /**
+   * Appends a step to unmute the current actor.
+   *
+   * @returns The current instance for method chaining.
+   */
+  unmute () {
+    this.append(StepActorUnmute<this>)
+    return this
+  }
 }

lib/trotsky.ts

@@ -78,10 +78,12 @@ export * from "./core/StepActorFollowers"
 export * from "./core/StepActorFollowings"
 export * from "./core/StepActorLikes"
 export * from "./core/StepActorLists"
+export * from "./core/StepActorMute"
 export * from "./core/StepActorPosts"
 export * from "./core/StepActorStreamPosts"
 export * from "./core/StepActorUnblock"
 export * from "./core/StepActorUnfollow"
+export * from "./core/StepActorUnmute"
 
 // Single post
 export * from "./core/StepCreatePost"

tests/core/StepActorMute.test.ts

@@ -0,0 +1,44 @@
+import { afterAll, beforeAll, describe, expect, test } from "@jest/globals"
+import { AtpAgent } from "@atproto/api"
+import { TestNetwork, SeedClient, usersSeed } from "@atproto/dev-env"
+
+import { Trotsky } from "../../lib/trotsky"
+
+describe("StepActorMute", () => {
+  let network: TestNetwork
+  let agent: AtpAgent
+  let sc: SeedClient
+  let alice: { "did": string; "handle": string; "password": string }
+  let bob: { "did": string; "handle": string; "password": string }
+
+  beforeAll(async () => {
+    network = await TestNetwork.create({ "dbPostgresSchema": "step_actor_mute" })
+    agent = network.pds.getClient()
+
+    sc = network.getSeedClient()
+    await usersSeed(sc)
+
+    bob = sc.accounts[sc.dids.bob]
+    alice = sc.accounts[sc.dids.alice]
+
+    await network.processAll()
+    await agent.login({ "identifier": bob.handle, "password": bob.password })
+  })
+
+  afterAll(async () => {
+    await network.close()
+  })
+
+  test("mute Alice", async () => {
+    await Trotsky.init(agent).actor(alice.handle).mute().wait(1e3).run()
+    const { "data": { mutes } } = await agent.app.bsky.graph.getMutes()
+
+    expect(mutes).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          "handle": alice.handle
+        })
+      ])
+    )
+  })
+})

tests/core/StepActorUnmute.test.ts

@@ -0,0 +1,62 @@
+import { afterAll, beforeAll, describe, expect, test } from "@jest/globals"
+import { AtpAgent } from "@atproto/api"
+import { TestNetwork, SeedClient, usersSeed } from "@atproto/dev-env"
+
+import { Trotsky } from "../../lib/trotsky"
+
+describe("StepActorUnmute", () => {
+  let network: TestNetwork
+  let agent: AtpAgent
+  let sc: SeedClient
+  let alice: { "did": string; "handle": string; "password": string }
+  let bob: { "did": string; "handle": string; "password": string }
+  let carol: { "did": string; "handle": string; "password": string }
+
+  beforeAll(async () => {
+    network = await TestNetwork.create({ "dbPostgresSchema": "step_actor_unmute" })
+    agent = network.pds.getClient()
+
+    sc = network.getSeedClient()
+    await usersSeed(sc)
+
+    bob = sc.accounts[sc.dids.bob]
+    alice = sc.accounts[sc.dids.alice]
+    carol = sc.accounts[sc.dids.carol]
+
+    await network.processAll()
+    await agent.login({ "identifier": bob.handle, "password": bob.password })
+  })
+
+  afterAll(async () => {
+    await network.close()
+  })
+
+  test("unmute Alice", async () => {
+    await Trotsky.init(agent).actor(alice.handle).mute().wait(1e3).run()
+    await Trotsky.init(agent).actor(alice.handle).unmute().wait(1e3).run()
+
+    const { "data": { mutes } } = await agent.app.bsky.graph.getMutes()
+
+    expect(mutes).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          "handle": alice.handle
+        })
+      ])
+    )
+  })
+
+  test("unmute Carol does nothing even if she is not muted", async () => {
+    await Trotsky.init(agent).actor(carol.handle).unmute().wait(1e3).run()
+
+    const { "data": { mutes } } = await agent.app.bsky.graph.getMutes()
+
+    expect(mutes).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          "handle": carol.handle
+        })
+      ])
+    )
+  })
+})