A framework for creating ActivityPub bots
Classes
A view of a Repository which is scoped to a single bot actor
identifier. It exposes the same operations as Repository without
the identifier parameter, which is bound at construction time.
- addFollowee(): Promise<void>followeeId: URL,follow: Follow
Adds a followee to the repository.
- addFollower(): Promise<void>followId: URL,follower: Actor
Adds a follower to the repository.
- addMessage(): Promise<void>id: Uuid,activity: Create | Announce
Adds a message to the repository.
- addQuoteAuthorization(): Promise<void>id: Uuid,authorization: QuoteAuthorization
Adds a quote authorization stamp to the repository.
- addQuoteAuthorizationReference(): Promise<void>authorization: URL,messageId: Uuid,attribution?: URL
Adds a received quote authorization reference.
- addSentFollow(): Promise<void>id: Uuid,follow: Follow
Adds a sent follow request to the repository.
- countFollowers(): Promise<number>
Counts the number of followers in the repository.
- countMessages(): Promise<number>
Counts the number of messages in the repository.
- countVoters(messageId: Uuid): Promise<number>
Counts the number of voters in a poll. Even if the poll allows multiple selections, each voter is counted only once.
- countVotes(messageId: Uuid): Promise<Readonly<Record<string, number>>>
Counts the votes for each option in a poll.
- findQuoteAuthorization(interactingObject: URL): Promise<QuoteAuthorization | undefined>
Finds a quote authorization stamp by the quote post it authorizes.
- findQuoteAuthorizationReference(authorization: URL): Promise<Uuid | undefined>
Finds a message by received quote authorization stamp URI.
- findQuoteAuthorizationReferenceAttribution(authorization: URL): Promise<URL | undefined>
Finds the actor that issued a received quote authorization stamp.
- getFollowee(followeeId: URL): Promise<Follow | undefined>
Gets a followee from the repository.
- getFollowers(options?: RepositoryGetFollowersOptions): AsyncIterable<Actor>
Gets followers from the repository.
- getKeyPairs(): Promise<CryptoKeyPair[] | undefined>
Gets the key pairs of the bot actor.
- getMessage(id: Uuid): Promise<Create | Announce | undefined>
Gets a message from the repository.
- getMessages(options?: RepositoryGetMessagesOptions): AsyncIterable<Create | Announce>
Gets messages from the repository.
- getQuoteAuthorization(id: Uuid): Promise<QuoteAuthorization | undefined>
Gets a quote authorization stamp from the repository.
- getSentFollow(id: Uuid): Promise<Follow | undefined>
Gets a sent follow request from the repository.
- hasFollower(followerId: URL): Promise<boolean>
Checks if the repository has a follower.
- identifier: string
The identifier of the bot actor this view is scoped to.
- removeFollowee(followeeId: URL): Promise<Follow | undefined>
Removes a followee from the repository.
- removeFollower(): Promise<Actor | undefined>followId: URL,followerId: URL
Removes a follower from the repository.
- removeMessage(id: Uuid): Promise<Create | Announce | undefined>
Removes a message from the repository.
- removeQuoteAuthorization(id: Uuid): Promise<QuoteAuthorization | undefined>
Removes a quote authorization stamp from the repository.
- removeQuoteAuthorizationReference(authorization: URL): Promise<void>
Removes a received quote authorization reference.
- removeSentFollow(id: Uuid): Promise<Follow | undefined>
Removes a sent follow request from the repository.
- repository: Repository
The underlying repository.
- setKeyPairs(keyPairs: CryptoKeyPair[]): Promise<void>
Sets the key pairs of the bot actor.
- updateMessage(): Promise<boolean>id: Uuid,updater: (existing: Create | Announce) =>Create
| Announce
| undefined
| Promise<Create | Announce | undefined>Updates a message in the repository.
- vote(): Promise<void>messageId: Uuid,voterId: URL,option: string
Records a vote in a poll. If the same voter had already voted for the same option in a poll, the vote will be silently ignored.
A repository for storing bot data using a key-value store.
- addFollowee(): Promise<void>identifier: string,followeeId: URL,follow: FollowNo documentation available
- addFollower(): Promise<void>identifier: string,followRequestId: URL,follower: ActorNo documentation available
- addMessage(): Promise<void>identifier: string,id: Uuid,activity: Create | AnnounceNo documentation available
- addQuoteAuthorization(): Promise<void>identifier: string,id: Uuid,authorization: QuoteAuthorizationNo documentation available
- addQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URL,messageId: Uuid,attribution?: URLNo documentation available
- addSentFollow(): Promise<void>identifier: string,id: Uuid,follow: FollowNo documentation available
- countFollowers(identifier: string): Promise<number>No documentation available
- countMessages(identifier: string): Promise<number>No documentation available
- countVoters(): Promise<number>identifier: string,messageId: UuidNo documentation available
- countVotes(): Promise<Readonly<Record<string, number>>>identifier: string,messageId: UuidNo documentation available
- findFollowedBots(followeeId: URL): AsyncIterable<string>No documentation available
- findQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,interactingObject: URLNo documentation available
- findQuoteAuthorizationReference(): Promise<Uuid | undefined>identifier: string,authorization: URLNo documentation available
- findQuoteAuthorizationReferenceAttribution(): Promise<URL | undefined>identifier: string,authorization: URLNo documentation available
- findQuoteAuthorizationReferenceIdentifiers(authorization: URL): AsyncIterable<string>No documentation available
- forIdentifier(identifier: string): ActorScopedRepositoryNo documentation available
- getFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URLNo documentation available
- getFollowers(): AsyncIterable<Actor>identifier: string,options?: RepositoryGetFollowersOptionsNo documentation available
- getKeyPairs(identifier: string): Promise<CryptoKeyPair[] | undefined>No documentation available
- getMessage(): Promise<Create | Announce | undefined>identifier: string,id: UuidNo documentation available
- getMessages(): AsyncIterable<Create | Announce>identifier: string,options?: RepositoryGetMessagesOptionsNo documentation available
- getQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: UuidNo documentation available
- getSentFollow(): Promise<Follow | undefined>identifier: string,id: UuidNo documentation available
- hasFollower(): Promise<boolean>identifier: string,followerId: URLNo documentation available
- kv: KvStoreNo documentation available
- migrate(identifier: string): Promise<void>
Migrates data stored by BotKit 0.4 or earlier, which was not scoped by bot actor identifiers, so that it belongs to the given identifier.
- nonCasLocks: Map<string, Promise<void>>No documentation available
- prefix: KvKey
The key prefix under which all BotKit data is stored.
- removeFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URLNo documentation available
- removeFollower(): Promise<Actor | undefined>identifier: string,followRequestId: URL,actorId: URLNo documentation available
- removeMessage(): Promise<Create | Announce | undefined>identifier: string,id: UuidNo documentation available
- removeQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: UuidNo documentation available
- removeQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URLNo documentation available
- removeSentFollow(): Promise<Follow | undefined>identifier: string,id: UuidNo documentation available
- setKeyPairs(): Promise<void>identifier: string,keyPairs: CryptoKeyPair[]No documentation available
- updateMessage(): Promise<boolean>identifier: string,id: Uuid,updater: (existing: Create | Announce) =>Create
| Announce
| undefined
| Promise<Create | Announce | undefined>No documentation available - vote(): Promise<void>identifier: string,messageId: Uuid,voterId: URL,option: stringNo documentation available
A repository decorator that adds an in-memory cache layer on top of another repository. This is useful for improving performance by reducing the number of accesses to the underlying persistent storage, but it increases memory usage. The cache is not persistent and will be lost when the process exits.
- addFollowee(): Promise<void>identifier: string,followeeId: URL,follow: FollowNo documentation available
- addFollower(): Promise<void>identifier: string,followId: URL,follower: ActorNo documentation available
- addMessage(): Promise<void>identifier: string,id: Uuid,activity: Create | AnnounceNo documentation available
- addQuoteAuthorization(): Promise<void>identifier: string,id: Uuid,authorization: QuoteAuthorizationNo documentation available
- addQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URL,messageId: Uuid,attribution?: URLNo documentation available
- addSentFollow(): Promise<void>identifier: string,id: Uuid,follow: FollowNo documentation available
- cache: MemoryRepositoryNo documentation available
- countFollowers(identifier: string): Promise<number>No documentation available
- countMessages(identifier: string): Promise<number>No documentation available
- countVoters(): Promise<number>identifier: string,messageId: UuidNo documentation available
- countVotes(): Promise<Readonly<Record<string, number>>>identifier: string,messageId: UuidNo documentation available
- findFollowedBots(followeeId: URL): AsyncIterable<string>No documentation available
- findQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,interactingObject: URLNo documentation available
- findQuoteAuthorizationReference(): Promise<Uuid | undefined>identifier: string,authorization: URLNo documentation available
- findQuoteAuthorizationReferenceAttribution(): Promise<URL | undefined>identifier: string,authorization: URLNo documentation available
- findQuoteAuthorizationReferenceIdentifiers(authorization: URL): AsyncIterable<string>No documentation available
- forIdentifier(identifier: string): ActorScopedRepositoryNo documentation available
- getFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URLNo documentation available
- getFollowers(): AsyncIterable<Actor>identifier: string,options?: RepositoryGetFollowersOptionsNo documentation available
- getKeyPairs(identifier: string): Promise<CryptoKeyPair[] | undefined>No documentation available
- getMessage(): Promise<Create | Announce | undefined>identifier: string,id: UuidNo documentation available
- getMessages(): AsyncIterable<Create | Announce>identifier: string,options?: RepositoryGetMessagesOptionsNo documentation available
- getQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: UuidNo documentation available
- getSentFollow(): Promise<Follow | undefined>identifier: string,id: UuidNo documentation available
- hasFollower(): Promise<boolean>identifier: string,followerId: URLNo documentation available
- migrate(identifier: string): Promise<void>
Migrates data stored by BotKit 0.4 or earlier in the underlying repository, so that it belongs to the given identifier. The cache is not involved: it starts empty and only ever holds values read after the migration.
- removeFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URLNo documentation available
- removeFollower(): Promise<Actor | undefined>identifier: string,followId: URL,followerId: URLNo documentation available
- removeMessage(): Promise<Create | Announce | undefined>identifier: string,id: UuidNo documentation available
- removeQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: UuidNo documentation available
- removeQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URLNo documentation available
- removeSentFollow(): Promise<Follow | undefined>identifier: string,id: UuidNo documentation available
- setKeyPairs(): Promise<void>identifier: string,keyPairs: CryptoKeyPair[]No documentation available
- underlying: RepositoryNo documentation available
- updateMessage(): Promise<boolean>identifier: string,id: Uuid,updater: (existing: Create | Announce) =>Create
| Announce
| undefined
| Promise<Create | Announce | undefined>No documentation available - vote(): Promise<void>identifier: string,messageId: Uuid,voterId: URL,option: stringNo documentation available
A repository for storing bot data in memory. This repository is not persistent and is only suitable for testing or development.
- addFollowee(): Promise<void>identifier: string,followeeId: URL,follow: FollowNo documentation available
- addFollower(): Promise<void>identifier: string,followId: URL,follower: ActorNo documentation available
- addMessage(): Promise<void>identifier: string,id: Uuid,activity: Create | AnnounceNo documentation available
- addQuoteAuthorization(): Promise<void>identifier: string,id: Uuid,authorization: QuoteAuthorizationNo documentation available
- addQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URL,messageId: Uuid,attribution?: URLNo documentation available
- addSentFollow(): Promise<void>identifier: string,id: Uuid,follow: FollowNo documentation available
- countFollowers(identifier: string): Promise<number>No documentation available
- countMessages(identifier: string): Promise<number>No documentation available
- countVoters(): Promise<number>identifier: string,messageId: UuidNo documentation available
- countVotes(): Promise<Readonly<Record<string, number>>>identifier: string,messageId: UuidNo documentation available
- findFollowedBots(followeeId: URL): AsyncIterable<string>No documentation available
- findQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,interactingObject: URLNo documentation available
- findQuoteAuthorizationReference(): Promise<Uuid | undefined>identifier: string,authorization: URLNo documentation available
- findQuoteAuthorizationReferenceAttribution(): Promise<URL | undefined>identifier: string,authorization: URLNo documentation available
- findQuoteAuthorizationReferenceIdentifiers(authorization: URL): AsyncIterable<string>No documentation available
- forIdentifier(identifier: string): ActorScopedRepositoryNo documentation available
- getFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URLNo documentation available
- getFollowers(): AsyncIterable<Actor>identifier: string,options?: RepositoryGetFollowersOptionsNo documentation available
- getKeyPairs(identifier: string): Promise<CryptoKeyPair[] | undefined>No documentation available
- getMessage(): Promise<Create | Announce | undefined>identifier: string,id: UuidNo documentation available
- getMessages(): AsyncIterable<Create | Announce>identifier: string,options?: RepositoryGetMessagesOptionsNo documentation available
- getQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: UuidNo documentation available
- getSentFollow(): Promise<Follow | undefined>identifier: string,id: UuidNo documentation available
- hasFollower(): Promise<boolean>identifier: string,followerId: URLNo documentation available
- removeFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URLNo documentation available
- removeFollower(): Promise<Actor | undefined>identifier: string,followId: URL,followerId: URLNo documentation available
- removeMessage(): Promise<Create | Announce | undefined>identifier: string,id: UuidNo documentation available
- removeQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: UuidNo documentation available
- removeQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URLNo documentation available
- removeSentFollow(): Promise<Follow | undefined>identifier: string,id: UuidNo documentation available
- setKeyPairs(): Promise<void>identifier: string,keyPairs: CryptoKeyPair[]No documentation available
- updateMessage(): Promise<boolean>identifier: string,id: Uuid,updater: (existing: Create | Announce) =>Create
| Announce
| undefined
| Promise<Create | Announce | undefined>No documentation available - vote(): Promise<void>identifier: string,messageId: Uuid,voterId: URL,option: stringNo documentation available
Functions
Creates an Instance that can host multiple bots sharing the same infrastructure.
Renders a custom emoji. You can use this function to create a CustomEmojiText tree.
Applies <em> tag to a text. You can use this function to create an
EmText tree.
Creates a hashtag. You can use this function to create a HashtagText tree.
A type guard that checks if a value is a single emoji character.
Creates a link to the given href with the label. You can use this
function to create a LinkText tree.
Creates a link to the given href with the label. You can use this
function to create a LinkText tree.
Creates a link to the given href with the label. You can use this
function to create a LinkText tree.
Mentions an actor by its fediverse handle. You can use this function to create a MentionText tree. The label of the mention will be the same as the handle.
Mentions an actor by its fediverse handle. You can use this function to create a MentionText tree. The label of the mention will be the same as the handle.
Mentions an actor by its fediverse handle. You can use this function to create a MentionText tree. The label of the mention will be the same as the handle.
Mentions an actor by its fediverse handle. You can use this function to create a MentionText tree. The label of the mention will be the same as the handle.
Normalizes a quote policy option into the two-axis form.
A function that creates a PlainText tree. It only does two simple things:
Applies <strong> tag to a text. You can use this function to create a
StrongText tree.
Interfaces
A bot that can interact with the ActivityPub network.
- addCustomEmojis<TEmojiName extends string>(emojis: Readonly<Record<TEmojiName, CustomEmoji>>): Readonly<Record<TEmojiName, DeferredCustomEmoji<TContextData>>>
Defines custom emojis for the bot. The custom emojis are used for rendering the bot's profile and posts. The custom emojis are defined by their names, and the names are used as the keys of the emojis.
- federation: Federation<TContextData>
An internal Fedify federation instance. Normally you don't need to access this directly.
- fetch(): Promise<Response>request: Request,contextData: TContextData
The fetch API for handling HTTP requests. You can pass this to an HTTP server (e.g.,
Deno.serve(),Bun.serve()) to handle incoming requests. - getSession(): Session<TContextData>origin: string | URL,contextData: TContextData
Gets a new session to control the bot for a specific origin and context data.
- identifier: string
The internal identifier for the bot actor. It is used for the actor URI.
The event handlers a bot can register. Assigning a handler to one of these properties makes the bot react to the corresponding ActivityPub activity.
- onAcceptFollow: AcceptEventHandler<TContextData>
An event handler invoked when a follow request the bot sent is accepted.
- onFollow: FollowEventHandler<TContextData>
An event handler for a follow request to the bot.
- onLike: LikeEventHandler<TContextData>
An event handler for a like of a message.
- onMention: MentionEventHandler<TContextData>
An event handler for a message mentioned to the bot.
- onMessage: MessageEventHandler<TContextData>
An event handler for a message shown to the bot's timeline. To listen to this event, your bot needs to follow others first.
- onQuote: QuoteEventHandler<TContextData>
An event handler for a quote of the bot's message.
- onQuoteAccepted: QuoteAcceptedEventHandler<TContextData>
An event handler invoked when a quote request the bot sent is accepted.
- onQuoteRejected: QuoteRejectedEventHandler<TContextData>
An event handler invoked when a quote request the bot sent is rejected.
- onQuoteRequest: QuoteRequestEventHandler<TContextData>
An event handler for a quote request to the bot.
- onQuoteRevoked: QuoteRevokedEventHandler<TContextData>
An event handler invoked when a quote authorization for the bot's quote post is revoked.
- onReact: ReactionEventHandler<TContextData>
An event handler for an emoji reaction to a message.
- onRejectFollow: RejectEventHandler<TContextData>
An event handler invoked when a follow request the bot sent is rejected.
- onReply: ReplyEventHandler<TContextData>
An event handler for a reply to the bot.
- onSharedMessage: SharedMessageEventHandler<TContextData>
An event handler for a message shared to the bot. To listen to this event, your bot needs to follow others first.
- onUnfollow: UnfollowEventHandler<TContextData>
An event handler for an unfollow event from the bot.
- onUnlike: UnlikeEventHandler<TContextData>
An event handler for an undoing of a like of a message.
- onUnreact: UndoneReactionEventHandler<TContextData>
An event handler for an undoing of an emoji reaction to a message.
- onVote: VoteEventHandler<TContextData>
An event handler for a vote in a poll. This event is only triggered when the bot is the author of the poll, and the vote is made by another actor. If the poll allows multiple selections, this event is triggered multiple times, once for each option selected by the actor.
A group of dynamically hosted bots sharing the same event handlers. A group is created by passing a BotDispatcher to Instance.createBot; the dispatcher resolves individual bots on demand, and the handlers registered on the group are invoked for every bot it resolves. Handlers can tell which bot they are running as through Session.bot.
- getSession(): Promise<Session<TContextData>>origin: string | URL,identifier: string,contextData: TContextData
Gets a new session to control one of the group's bots for a specific origin and context data.
The profile of a bot actor hosted on an Instance. It configures everything about a bot except its identifier and the shared infrastructure, which belong to the instance.
- class: Service | Application
The type of the bot actor. It should be either
ServiceorApplication. - followerPolicy: "accept" | "reject" | "manual"
How to handle incoming follow requests. Note that this behavior can be overridden by manually invoking FollowRequest.accept or FollowRequest.reject in the BotEventHandlers.onFollow event handler.
- icon: URL | Image
The avatar URL of the bot. It can be changed after the bot is federated.
- image: URL | Image
The header image URL of the bot. It can be changed after the bot is federated.
- name: string
The display name of the bot. It can be changed after the bot is federated.
- properties: Record<string, Text<"block" | "inline", TContextData>>
The custom properties of the bot. It can be changed after the bot is federated.
- quotePolicy: QuotePolicyOption
Who can quote messages published by the bot.
- summary: Text<"block", TContextData>
The description of the bot. It can be changed after the bot is federated.
- username: string
The username of the bot. It will be a part of the fediverse handle. It can be changed after the bot is federated.
A specialized Bot tpe that doesn't require context data.
- fetch(request: Request): Promise<Response>
The fetch API for handling HTTP requests. You can pass this to an HTTP server (e.g.,
Deno.serve(),Bun.serve()) to handle incoming requests. - getSession(): Session<void>origin: string | URL,contextData: void
Gets a new session to control the bot for a specific origin and context data.
Options for creating a dynamic BotGroup.
- mapUsername(): string | null | Promise<string | null>ctx: Context<TContextData>,username: string
Maps a WebFinger username to the identifier of a bot the group's dispatcher can resolve. If omitted, usernames are assumed to equal identifiers.
Options for creating a bot.
- behindProxy: boolean
Whether to trust
X-Forwarded-*headers. If your bot application is behind an L7 reverse proxy, turn it on. - class: Service | Application
The type of the bot actor. It should be either
ServiceorApplication. - followerPolicy: "accept" | "reject" | "manual"
How to handle incoming follow requests. Note that this behavior can be overridden by manually invoking FollowRequest.accept or FollowRequest.reject in the Bot.onFollow event handler.
- icon: URL | Image
The avatar URL of the bot. It can be changed after the bot is federated.
- identifier: string
The internal identifier of the bot. Since it is used for the actor URI, it should not be changed after the bot is federated.
- image: URL | Image
The header image URL of the bot. It can be changed after the bot is federated.
- kv: KvStore
The underlying key-value store to use for storing data.
- name: string
The display name of the bot. It can be changed after the bot is federated.
- pages: PagesOptions
The options for the web pages of the bot. If omitted, the default options will be used.
- properties: Record<string, Text<"block" | "inline", TContextData>>
The custom properties of the bot. It can be changed after the bot is federated.
- queue: MessageQueue
The underlying message queue to use for handling incoming and outgoing activities. If omitted, incoming activities are processed immediately, and outgoing activities are sent immediately.
- quotePolicy: QuotePolicyOption
Who can quote messages published by the bot.
- repository: Repository
The underlying repository to use for storing data. If omitted, KvRepository will be used.
- software: Software
The software information of the bot. If omitted, the NodeInfo protocol will be unimplemented.
- summary: Text<"block", TContextData>
The description of the bot. It can be changed after the bot is federated.
- username: string
The username of the bot. It will be a part of the fediverse handle. It can be changed after the bot is federated.
Options for creating an Instance.
- behindProxy: boolean
Whether to trust
X-Forwarded-*headers. If your instance is behind an L7 reverse proxy, turn it on. - instanceActorIdentifier: string
The identifier of the instance actor: an internal
Applicationactor the instance uses for signing shared-inbox related requests. Override it when the default identifier collides with a bot you want to host. Since it is used for the actor URI, it should not be changed after the instance is federated. - kv: KvStore
The underlying key–value store to use for storing data.
- legacyObjectUris: { readonly identifier: string; }
Configures the recognition of local object URIs in the legacy (pre-0.5) format, which did not carry the owning bot actor identifier. Set this when the instance hosts a bot that was deployed with BotKit 0.4 or earlier, so that object URIs stored by remote servers keep working.
- pages: PagesOptions
The options for the web pages of the instance. If omitted, the default options will be used.
- queue: MessageQueue
The underlying message queue to use for handling incoming and outgoing activities. If omitted, incoming activities are processed immediately, and outgoing activities are sent immediately.
- repository: Repository
The repository to use for storing bot data. A single repository stores the data of every bot hosted on the instance, scoped by their identifiers. If omitted, a KvRepository backed by
kvwill be used. - software: Software
The software information of the instance. If omitted, the NodeInfo protocol will be unimplemented.
A follow request to the bot.
A server instance that can host multiple bots. An instance owns the shared infrastructure—the key–value store, the message queue, the repository, and HTTP handling—while each bot hosted on it has its own actor identity and event handlers.
- addCustomEmojis<TEmojiName extends string>(emojis: Readonly<Record<TEmojiName, CustomEmoji>>): Readonly<Record<TEmojiName, DeferredCustomEmoji<TContextData>>>
Defines custom emojis for the instance. The custom emojis are shared by all bots hosted on the instance and are used for rendering their profiles and posts.
- createBot(): Bot<TContextData>identifier: string,profile: BotProfile<TContextData>
Creates a bot with a fixed identifier and profile, hosted on this instance.
- federation: Federation<TContextData>
An internal Fedify federation instance. Normally you don't need to access this directly.
- fetch(): Promise<Response>request: Request,contextData: TContextData
The fetch API for handling HTTP requests. You can pass this to an HTTP server (e.g.,
Deno.serve(),Bun.serve()) to handle incoming requests.
A specialized Instance type that doesn't require context data.
- fetch(request: Request): Promise<Response>
The fetch API for handling HTTP requests. You can pass this to an HTTP server (e.g.,
Deno.serve(),Bun.serve()) to handle incoming requests.
Options for creating a KvRepository.
- prefix: KvKey
The key prefix under which all BotKit data is stored. Data belonging to a bot actor is stored under
[...prefix, "bots", identifier, ...], and instance-wide indices are stored under[...prefix, "index", ...].
A like of a message. It is a thin wrapper around a Like, which is
a Fedify object.
A message in the ActivityPub network. It is a thin wrapper around
a Fedify object: an Article, a ChatMessage, a Note, or a Question.
- actor: Actor
The actor who published the message.
- attachments: readonly Document[]
The media attachments of the message.
- hashtags: readonly Hashtag[]
The hashtags used in the message.
- html: string
The HTML content of the message.
- id: URL
The URI of the message.
- language: Intl.Locale
The language of the message if the content is tagged with a language.
- like(): Promise<AuthorizedLike<TContextData>>
Likes the message.
- mentions: readonly Actor[]
The actors mentioned in the message.
- published: Temporal.Instant
The published time of the message.
- quoteApproved: boolean
Whether this message's quote target has been approved according to FEP-044f. It is
undefinedwhen this message is not a quote. - quotePolicy: QuotePolicy
The quote policy advertised by this message, if present.
- quoteTarget: Message<MessageClass, TContextData>
The message quoted by this message, if any.
- raw: T
The underlying raw message object.
- react(emoji: Emoji | CustomEmoji | DeferredCustomEmoji<TContextData>): Promise<AuthorizedReaction<TContextData>>
Reacts to the message with a Unicode emoji or a custom emoji.
- reply(): Promise<AuthorizedMessage<Note, TContextData>>text: Text<"block", TContextData>,options?: SessionPublishOptions<TContextData>
Publishes a reply to the message.
- replyTarget: Message<MessageClass, TContextData>
The original message in reply to, if the message is a reply.
- share(options?: MessageShareOptions): Promise<AuthorizedSharedMessage<T, TContextData>>
Shares the message.
- text: string
The plain text content of the message.
- updated: Temporal.Instant
The updated time of the message, if it is updated.
- visibility: MessageVisibility
The visibility of the message.
Options for the web pages of the bot.
- color:"amber"
| "azure"
| "blue"
| "cyan"
| "fuchsia"
| "green"
| "grey"
| "indigo"
| "jade"
| "lime"
| "orange"
| "pink"
| "pumpkin"
| "purple"
| "red"
| "sand"
| "slate"
| "violet"
| "yellow"
| "zinc"The color of the theme. It will be used for the theme color of the web pages. The default color is
"green". - css: string
The CSS code for the bot. It will be used for the custom CSS of the web pages.
- theme: "auto" | "light" | "dark"
The color scheme of the web pages.
"auto"follows the visitor's operating system preference, while"light"and"dark"force a fixed scheme. The default is"auto".
An interface representing a poll.
A quote policy for messages published by the bot.
A quote request to the bot.
- accept(signal?: AbortSignal): Promise<void>
Accepts the quote request.
- actor: Actor
The actor requesting quote authorization.
- id: URL
The URI of the quote request.
- quote: Message<MessageClass, TContextData>
The message that quotes the bot's message.
- raw: RawQuoteRequest
The raw quote request object.
- reject(signal?: AbortSignal): Promise<void>
Rejects the quote request.
- state: "pending" | "accepted" | "rejected"
The state of the quote request.
- target: AuthorizedMessage<MessageClass, TContextData>
The bot's message being quoted.
An emoji reaction to a message. It is a thin wrapper around an
EmojiReact, which is a Fedify object.
- actor: Actor
The actor who reacted to the message.
- emoji: Emoji | CustomEmoji
The emoji that was used in the reaction. It can be either a Unicode emoji or a custom emoji.
- id: URL
The URI of the reaction activity.
- message: Message<MessageClass, TContextData>
The message that was reacted.
- raw: RawLike | EmojiReact
The underlying raw
LikeorEmojiReactactivity.
A read-only view of a bot actor's identity and profile. It is exposed through Session.bot so that event handlers can tell which bot they are running as without being able to mutate the bot (e.g. reassign its event handlers).
- class: Service | Application
The type of the bot actor. It is either
ServiceorApplication. - followerPolicy: "accept" | "reject" | "manual"
How the bot handles incoming follow requests.
- icon: URL | Image
The avatar URL of the bot.
- identifier: string
The internal identifier for the bot actor. It is used for the actor URI.
- image: URL | Image
The header image URL of the bot.
- name: string
The display name of the bot.
- quotePolicy: QuotePolicyOption
How the bot handles incoming quote requests for its messages.
- username: string
The username of the bot. It is a part of the fediverse handle.
A repository for storing bot data.
- addFollowee(): Promise<void>identifier: string,followeeId: URL,follow: Follow
Adds a followee to the repository.
- addFollower(): Promise<void>identifier: string,followId: URL,follower: Actor
Adds a follower to the repository.
- addMessage(): Promise<void>identifier: string,id: Uuid,activity: Create | Announce
Adds a message to the repository.
- addQuoteAuthorization(): Promise<void>identifier: string,id: Uuid,authorization: QuoteAuthorization
Adds a quote authorization stamp to the repository.
- addQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URL,messageId: Uuid,attribution?: URL
Adds a reference to a quote authorization stamp received for one of the bot's own quote posts.
- addSentFollow(): Promise<void>identifier: string,id: Uuid,follow: Follow
Adds a sent follow request to the repository.
- countFollowers(identifier: string): Promise<number>
Counts the number of followers in the repository.
- countMessages(identifier: string): Promise<number>
Counts the number of messages in the repository.
- countVoters(): Promise<number>identifier: string,messageId: Uuid
Counts the number of voters in a poll. Even if the poll allows multiple selections, each voter is counted only once.
- countVotes(): Promise<Readonly<Record<string, number>>>identifier: string,messageId: Uuid
Counts the votes for each option in a poll. If the poll allows multiple selections, each option is counted separately, and the same voter can vote for multiple options.
- findFollowedBots(followeeId: URL): AsyncIterable<string>
Finds the identifiers of the bot actors that follow the given actor. This is the reverse lookup of Repository.getFollowee: it answers the question “which bots on this instance follow this remote actor?”, which is used for routing incoming activities from followed actors to the right bots.
- findQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,interactingObject: URL
Finds a quote authorization stamp by the quote post it authorizes.
- findQuoteAuthorizationReference(): Promise<Uuid | undefined>identifier: string,authorization: URL
Finds the bot's quote message that depends on a received quote authorization stamp.
- findQuoteAuthorizationReferenceAttribution(): Promise<URL | undefined>identifier: string,authorization: URL
Finds the actor that issued a received quote authorization stamp.
- findQuoteAuthorizationReferenceIdentifiers(authorization: URL): AsyncIterable<string>
Finds bot identifiers whose quote messages depend on a received quote authorization stamp.
- forIdentifier(identifier: string): ActorScopedRepository
Returns a view of this repository which is scoped to the given bot actor identifier. The returned view exposes the same operations without the
identifierparameter. - getFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URL
Gets a followee from the repository.
- getFollowers(): AsyncIterable<Actor>identifier: string,options?: RepositoryGetFollowersOptions
Gets followers from the repository.
- getKeyPairs(identifier: string): Promise<CryptoKeyPair[] | undefined>
Gets the key pairs of a bot actor.
- getMessage(): Promise<Create | Announce | undefined>identifier: string,id: Uuid
Gets a message from the repository.
- getMessages(): AsyncIterable<Create | Announce>identifier: string,options?: RepositoryGetMessagesOptions
Gets messages from the repository.
- getQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: Uuid
Gets a quote authorization stamp from the repository.
- getSentFollow(): Promise<Follow | undefined>identifier: string,id: Uuid
Gets a sent follow request from the repository.
- hasFollower(): Promise<boolean>identifier: string,followerId: URL
Checks if the repository has a follower.
- migrate(identifier: string): Promise<void>
Migrates data stored by BotKit 0.4 or earlier, which was not scoped by bot actor identifiers, so that it belongs to the given identifier. Implementations should make this operation idempotent: calling it again after a successful migration should be a no-op.
- removeFollowee(): Promise<Follow | undefined>identifier: string,followeeId: URL
Removes a followee from the repository.
- removeFollower(): Promise<Actor | undefined>identifier: string,followId: URL,followerId: URL
Removes a follower from the repository.
- removeMessage(): Promise<Create | Announce | undefined>identifier: string,id: Uuid
Removes a message from the repository.
- removeQuoteAuthorization(): Promise<QuoteAuthorization | undefined>identifier: string,id: Uuid
Removes a quote authorization stamp from the repository.
- removeQuoteAuthorizationReference(): Promise<void>identifier: string,authorization: URL
Removes the reference to a received quote authorization stamp.
- removeSentFollow(): Promise<Follow | undefined>identifier: string,id: Uuid
Removes a sent follow request from the repository.
- setKeyPairs(): Promise<void>identifier: string,keyPairs: CryptoKeyPair[]
Sets the key pairs of a bot actor.
- updateMessage(): Promise<boolean>identifier: string,id: Uuid,updater: (existing: Create | Announce) =>Create
| Announce
| undefined
| Promise<Create | Announce | undefined>Updates a message in the repository.
- vote(): Promise<void>identifier: string,messageId: Uuid,voterId: URL,option: string
Records a vote in a poll. If the same voter had already voted for the same option in a poll, the vote will be silently ignored.
A session to control the bot.
- actorHandle: `@${string}@${string}`
The fediverse handle of the bot actor. It starts with
@. - actorId: URL
The URI of the bot actor.
- bot: ReadonlyBot
A read-only view of the bot to which the session belongs. It exposes the bot's identity and profile (e.g.
identifier,username,name) without allowing event handlers to be reassigned through it. - context: Context<TContextData>
The Fedify context of the session.
- follow(actor: Actor | URL | string): Promise<void>
Send a follow request to the specified actor.
- follows(actor: Actor | URL | string): Promise<boolean>
Checks whether the bot is following the specified actor.
- getActor(): Promise<Actor>
Gets the
Actorobject of the bot. - getOutbox(options?: SessionGetOutboxOptions): AsyncIterable<AuthorizedMessage<MessageClass, TContextData>>
Gets messages from the bot's outbox.
- publish(): Promise<AuthorizedMessage<Note, TContextData>>content: Text<"block", TContextData>,options?: SessionPublishOptions<TContextData>
Publishes a message attributed to the bot.
- republishProfile(): Promise<void>
Republishes the bot profile to its followers.
- unfollow(actor: Actor | URL | string): Promise<void>
Unfollow the specified actor.
Options for getting messages from the bot's outbox.
- limit: number
The maximum number of messages to get. If omitted, no limit will be applied.
- order: "oldest" | "newest"
The order of the messages. If omitted,
"newest"will be used. - since: Temporal.Instant
The timestamp to get messages created at or after this time. If omitted, no limit will be applied.
- until: Temporal.Instant
The timestamp to get messages created at or before this time. If omitted, no limit will be applied.
Options for publishing a message.
- attachments: Document[]
The media attachments of the published message.
- language: string | Intl.Locale
The language of the published message.
- quotePolicy: QuotePolicyOption
Who can quote the published message.
- quoteTarget: Message<MessageClass, TContextData>
The message to quote in the published message.
- visibility: Exclude<MessageVisibility, "unknown">
The visibility of the published message. If omitted,
"public"will be used.
Options for publishing a message with a specific class.
- class: T extends Article ? Article : T extends ChatMessage ? ChatMessage : T extends Note ? Note : T extends Question ? Question : never
The class of the published message. If omitted,
Notewill be used.
A tree structure representing a text with formatting. It does not only render the text but also extract tags (e.g., mentions) from it.
- getCachedObjects(): Object[]
Gets cached objects. The result of this method depends on whether getHtml or getTags has been called before. It's used for optimizing the post rendering process, e.g., reusing once fetched remote objects.
- getHtml(session: Session<TContextData>): AsyncIterable<string>
Render a text tree as HTML.
- getTags(session: Session<TContextData>): AsyncIterable<Link | Object>
Extract tags (e.g., mentions) from a text tree.
- type: TType
The type of the text. It can be either
"block"or"inline".
- actor: Actor
The actor who voted.
- message: Message<Question, TContextData>
The question to which the poll belongs.
- option: string
The options selected by the actor. Note that this is a string even if the poll allows multiple selections. If the poll allows multiple selections, the options are represented as multiple Vote objects.
- poll: Poll
The poll to which the vote belongs.
- raw: Note
The underlying raw note object.
Type Aliases
An event handler invoked when a follow request the bot sent is accepted.
| null
| Promise<BotProfile<TContextData> | null>
A function that resolves the profile of a dynamically hosted bot from its identifier. It is invoked whenever an identifier needs to be resolved, e.g. for dispatching an actor or routing an incoming activity, so it should be fast; look profiles up from a database rather than computing them expensively.
A definition of a custom emoji. It can be either a remote image URL or a local image file.
A deferred Emoji (provided by Fedify), which is a function that
takes a Session and returns an Emoji. This is useful for
creating emojis that depend on the session data.
A branded type for a single emoji character (more exactly, a single Unicode grapheme cluster of emoji). This is used to represent a single emoji in a string format. It is not a full-fledged emoji object, but rather a string that is guaranteed to be a single emoji.
An event handler for a follow request to the bot.
An event handler for a like of a message.
An event handler for a message mentioned to the bot.
A possible message class.
An event handler for a message shown to the bot's timeline. To listen to this event, your bot needs to follow others first.
The visibility of a message.
The audience whose quote requests can be approved.
An event handler invoked when a quote request the bot sent is accepted.
An event handler for a quote of the bot's message.
A shorthand or full quote policy.
An event handler invoked when a quote request the bot sent is rejected.
An event handler for a quote request to the bot.
An event handler invoked when an authorization stamp for the bot's quote post is revoked.
An event handler for an emoji reaction to a message.
An event handler invoked when a follow request the bot sent is rejected.
An event handler for a reply to the bot.
An event handler for undoing an emoji reaction to a message.
An event handler for an unfollow event from the bot.
An event handler for undoing a like of a message.
An event handler for a vote in a poll. This event is only triggered when the bot is the author of the poll, and the vote is made by another actor. Note that if the poll allows multiple selections, this event is triggered multiple times, once for each option selected by the actor.
Variables
The default identifier of the instance actor: an internal Application
actor that an Instance uses for signing shared-inbox related
requests on behalf of the whole instance. It can be overridden through
the CreateInstanceOptions.instanceActorIdentifier option; either
way, bots cannot take the effective identifier.