doc: add examples

Author: pirhoo

lib/core/StepActor.ts

@@ -21,9 +21,32 @@ export type StepActorOutput = AppBskyActorGetProfile.OutputSchema
 
 /**
  * Represents a step for retrieving and handling an actor's profile using the Bluesky API.
+ *
  * @typeParam P - Type of the parent object.
  * @typeParam C - Type of the context object.
  * @typeParam O - Type of the output object, extending {@link StepActorOutput}.
+ *
+ * @example
+ * Get an actor's profile:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("bsky.app")
+ *   .tap((step) => {
+ *     console.log(step.context.displayName)
+ *     console.log(step.context.followersCount)
+ *   })
+ *   .run()
+ * ```
+ *
+ * @example
+ * Follow an actor:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("alice.bsky.social")
+ *   .follow()
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActor<P = StepBuilder, C = null, O extends StepActorOutput = StepActorOutput> extends ActorMixins<P, C, O> {

lib/core/StepActorBlock.ts

@@ -2,9 +2,33 @@ import { Step, type StepActor, type StepActorOutput } from "../trotsky"
 
 /**
  * Represents a step that performs an actor block 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.
+ *
+ * @example
+ * Block a specific actor:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("spammer.bsky.social")
+ *   .block()
+ *   .run()
+ * ```
+ *
+ * @example
+ * Block actors posting spam content:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .searchPosts({ q: "spam content" })
+ *   .take(10)
+ *   .each()
+ *   .author()
+ *   .block()
+ *   .wait(1000)
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorBlock<P = StepActor, C extends StepActorOutput = StepActorOutput, O = null> extends Step<P, C, O> {

lib/core/StepActorFollow.ts

@@ -2,9 +2,33 @@ import { Step, type StepActor, type StepActorOutput } from "../trotsky"
 
 /**
  * Represents a step that performs an actor follow operation using the agent.
+ *
  * @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.
+ *
+ * @example
+ * Follow a specific actor:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("alice.bsky.social")
+ *   .follow()
+ *   .run()
+ * ```
+ *
+ * @example
+ * Follow back all your followers:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("myhandle.bsky.social")
+ *   .followers()
+ *   .each()
+ *   .when((step) => !step?.context?.viewer?.following)
+ *   .follow()
+ *   .wait(2000)
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorFollow<P = StepActor, C extends StepActorOutput = StepActorOutput, O = null> extends Step<P, C, O> {

lib/core/StepActorFollowers.ts

@@ -27,9 +27,37 @@ export type StepActorFollowersQueryParamsCursor = StepActorFollowersQueryParams[
 /**
  * Represents a step for retrieving an actor's followers using the Bluesky API.
  * Supports paginated retrieval of followers.
+ *
  * @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, extending {@link StepActorFollowersOutput}.
+ *
+ * @example
+ * Get and iterate through an actor's followers:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("bsky.app")
+ *   .followers()
+ *   .each()
+ *   .tap((step) => {
+ *     console.log(`Follower: ${step.context.handle}`)
+ *   })
+ *   .run()
+ * ```
+ *
+ * @example
+ * Follow back all your followers:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("myhandle.bsky.social")
+ *   .followers()
+ *   .each()
+ *   .when((step) => !step?.context?.viewer?.following)
+ *   .follow()
+ *   .wait(2000)
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorFollowers<P = StepActor, C extends StepActorOutput = StepActorOutput, O extends StepActorFollowersOutput = StepActorFollowersOutput> extends StepActors<P, C, O> {  

lib/core/StepActorFollowings.ts

@@ -27,9 +27,38 @@ export type StepActorFollowingsQueryParamsCursor = StepActorFollowingsQueryParam
 /**
  * Represents a step for retrieving an actor's followings using the Bluesky API.
  * Supports paginated retrieval of followings.
+ *
  * @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, extending {@link StepActorFollowingsOutput}.
+ *
+ * @example
+ * Get and iterate through an actor's followings:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("bsky.app")
+ *   .followings()
+ *   .each()
+ *   .tap((step) => {
+ *     console.log(`Following: ${step.context.handle}`)
+ *   })
+ *   .run()
+ * ```
+ *
+ * @example
+ * Check which accounts follow you back:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("myhandle.bsky.social")
+ *   .followings()
+ *   .each()
+ *   .tap((step) => {
+ *     const mutual = step.context.viewer?.followedBy
+ *     console.log(`${step.context.handle}: ${mutual ? '✅' : '❌'}`)
+ *   })
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorFollowings<P = StepActor, C extends StepActorOutput = StepActorOutput, O extends StepActorFollowingsOutput = StepActorFollowingsOutput> extends StepActors<P, C, O> {

lib/core/StepActorLikes.ts

@@ -28,9 +28,38 @@ export type StepActorLikesQueryParamsCursor = StepActorLikesQueryParams["cursor"
 /**
  * Represents a step for retrieving an actor's likes using the Bluesky API.
  * Supports paginated retrieval of likes.
+ *
  * @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, extending {@link StepActorLikesOutput}.
+ *
+ * @example
+ * Get and display an actor's liked posts:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("alice.bsky.social")
+ *   .likes()
+ *   .take(20)
+ *   .each()
+ *   .tap((step) => {
+ *     console.log(`Liked: ${step.context.record.text}`)
+ *   })
+ *   .run()
+ * ```
+ *
+ * @example
+ * Like what your favorite users like:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("alice.bsky.social")
+ *   .likes()
+ *   .take(10)
+ *   .each()
+ *   .like()
+ *   .wait(2000)
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorLikes<P = StepActor, C extends StepActorOutput = StepActorOutput, O extends StepActorLikesOutput = StepActorLikesOutput> extends StepPosts<P, C, O> {

lib/core/StepActorLists.ts

@@ -25,11 +25,40 @@ export type StepActorListsQueryParamsCursor = StepActorListsQueryParams["cursor"
 
 /**
  * Represents step for retrieving the lists associated with a specific actor, extending the {@link StepLists} functionality.
- * 
+ *
  * @typeParam P - The parent step type, defaulting to {@link StepActor}.
  * @typeParam C - The context type, defaulting to {@link StepActorOutput}.
  * @typeParam O - The output type, defaulting to {@link StepActorListsOutput}.
- * 
+ *
+ * @example
+ * Get all lists created by an actor:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("alice.bsky.social")
+ *   .lists()
+ *   .each()
+ *   .tap((step) => {
+ *     console.log(`List: ${step.context.name}`)
+ *     console.log(`Purpose: ${step.context.purpose}`)
+ *   })
+ *   .run()
+ * ```
+ *
+ * @example
+ * Get members of all lists from an actor:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("alice.bsky.social")
+ *   .lists()
+ *   .each()
+ *   .members()
+ *   .each()
+ *   .tap((step) => {
+ *     console.log(step.context.handle)
+ *   })
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorLists<P = StepActor, C extends StepActorOutput = StepActorOutput, O extends StepListsOutput = StepActorListsOutput> extends StepLists<P, C, O> {

lib/core/StepActorMute.ts

@@ -2,9 +2,33 @@ 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.
+ *
+ * @example
+ * Mute a specific actor:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("spammer.bsky.social")
+ *   .mute()
+ *   .run()
+ * ```
+ *
+ * @example
+ * Mute actors with specific criteria:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .searchPosts({ q: "spam keyword" })
+ *   .take(10)
+ *   .each()
+ *   .author()
+ *   .mute()
+ *   .wait(1000)
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorMute<P = StepActor, C extends StepActorOutput = StepActorOutput, O = null> extends Step<P, C, O> {

lib/core/StepActorPosts.ts

@@ -28,9 +28,39 @@ export type StepActorPostsQueryParamsCursor = StepActorPostsQueryParams["cursor"
 /**
  * Represents a step for retrieving an actor's posts using the Bluesky API.
  * Supports paginated retrieval of posts.
+ *
  * @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, extending {@link StepActorPostsOutput}.
+ *
+ * @example
+ * Get an actor's recent posts:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("bsky.app")
+ *   .posts()
+ *   .take(10)
+ *   .each()
+ *   .tap((step) => {
+ *     console.log(step.context.record.text)
+ *   })
+ *   .run()
+ * ```
+ *
+ * @example
+ * Like an actor's popular posts:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("alice.bsky.social")
+ *   .posts()
+ *   .take(50)
+ *   .each()
+ *   .when((step) => step?.context?.likeCount > 10)
+ *   .like()
+ *   .wait(1000)
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorPosts<P = StepActor, C extends StepActorOutput = StepActorOutput, O extends StepActorPostsOutput = StepActorPostsOutput> extends StepPosts<P, C, O> {

lib/core/StepActorUnblock.ts

@@ -4,10 +4,33 @@ import { Step, type StepActor, type StepActorOutput } from "../trotsky"
 
 /**
  * Represents step that unblocks the current actor (if blocked).
- * 
+ *
  * @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`.
+ *
+ * @example
+ * Unblock a specific actor:
+ * ```ts
+ * await Trotsky.init(agent)
+ *   .actor("user.bsky.social")
+ *   .unblock()
+ *   .run()
+ * ```
+ *
+ * @example
+ * Unblock all blocked accounts:
+ * ```ts
+ * const { data: { blocks } } = await agent.app.bsky.graph.getBlocks()
+ *
+ * await Trotsky.init(agent)
+ *   .actors(blocks.map(b => b.did))
+ *   .each()
+ *   .unblock()
+ *   .wait(1000)
+ *   .run()
+ * ```
+ *
  * @public
  */
 export class StepActorUnblock<P = StepActor, C extends StepActorOutput = StepActorOutput, O = null> extends Step<P, C, O> {