Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/botnadzor/extension/llms.txt

Use this file to discover all available pages before exploring further.

Botnadzor Extension uses a service-oriented architecture where background services are registered via @webext-core/proxy-service and can be accessed from content scripts. All services are instantiated in src/entrypoints/background.ts.

​
Service Registration

Services are registered with typed keys defined in src/shared/proxy-service-keys.ts: 
export const authServiceKey: ProxyServiceKey<AuthService> = "auth-service";
export const affiliationServiceKey: ProxyServiceKey<AffiliationService> = "affiliation-service";
// ... other service keys

​
AffiliationService

Checks whether VK accounts are affiliated with known tags (bots, spam, etc.) by looking them up in static lists. Dependencies:
  • StaticListsService
  • UserConfigService
Key Methods: 
async checkAccount(
  vkDomain: VkDomain | InterpretedVkDomain
): Promise<AccountAffiliation | undefined>
Returns affiliation data including tags, colors, and visibility flags. Source: src/entrypoints/background/@services/affiliation-service.ts:33-101

​
AuthService

Manages authentication state with the Botnadzor API, including access codes, permissions, and point counts. Dependencies:
  • AliasManager (for dynamic API)
Key Methods: 
async checkAuth(): Promise<void>
Validates the current access code with the API. 
setAccessCode(accessCode: string): void
Sets a new access code and triggers validation. 
async pollAuthStatus(
  lastPollVersion: PollVersion | undefined
): Promise<PollResult<AuthStatus>>
Polls for changes to authentication status. 
getAuthStatus(): AuthStatus
Returns the current authentication state (empty, invalid, valid, or unknown). 
async fetchFromDynamicApiWithAccessCode<Method extends DynamicApiEndpointKey>(
  method: Method,
  payload?: DynamicApiEndpointInput<Method>
): Promise<DynamicApiEndpointOutcome<Method>>
Makes authenticated requests to the dynamic API. 
patchPermissionLookup(permissionLookup: PermissionLookup): void
Updates permissions after API operations that consume them. 
patchPointCount(pointCount: number): void
Updates point count after operations that consume points. Source: src/entrypoints/background/@services/auth-service.ts:46-271

​
CollectingService

Collects and uploads VK comment metadata to help build the Botnadzor database. Users must opt-in via settings. Dependencies:
  • AuthService
  • StaticListsService
  • UserConfigService
Key Methods: 
async collectCommentIfNeeded(
  commentToCollect: CommentToCollect
): Promise<void>
Collects a comment if the user has opted in and the wall isn’t skipped. 
async persistRegisteredCommentsIfNeeded(): Promise<void>
Persists collected comments to IndexedDB. 
async uploadPersistedCommentsIfNeeded(): Promise<void>
Uploads persisted comments to the server in batches. Data Flow:
  1. Comments are collected from the page
  2. Stored temporarily in memory
  3. Persisted to IndexedDB every 5 seconds
  4. Uploaded to server every 5 minutes (batches of 5-1000 comments)
  5. Old comments are pruned when storage exceeds 10,000 items
Source: src/entrypoints/background/@services/collecting-service.ts:86-715

​
DxConfigService

Manages developer experience configuration (only available when dxFeaturesEnabled is true in app config). Dependencies: None Key Methods: 
async get(): Promise<DxConfig>
Returns current DX configuration. 
set(newValue: DxConfig): void
Updates DX configuration. 
async poll(
  lastPollVersion: PollVersion | undefined
): Promise<PollResult<DxConfig>>
Polls for configuration changes. Source: src/entrypoints/background/@services/dx-config-service.ts:22-85

​
ExtensionVersionService

Determines extension version deprecation status and filters announcements/insertions by version range. Dependencies:
  • RootConfigService
  • StaticListsService
Key Methods: 
async getInfo(): Promise<ExtensionVersionInfo>
Returns version info including deprecation status and age. 
async getFilteredAnnouncements(
  filter: AnnouncementVersionFilter
): Promise<Array<StaticListItem<"announcements">>>
Returns announcements filtered by extension version. Filter can be "default" or "toast". 
async getFilteredInsertions(): Promise<Array<StaticListItem<"insertions">>>
Returns insertion configs filtered by extension version. Source: src/entrypoints/background/@services/extension-version-service.ts:35-167

​
FrontendService

Manages frontend base URLs with automatic alias failover when primary domains are unavailable. Dependencies:
  • AliasManager (for frontend)
Key Methods: 
async getBaseUrl(): Promise<string>
Returns the current frontend base URL (e.g., https://botnadzor.org). 
async pollBaseUrl(
  lastPollVersion: PollVersion | undefined
): Promise<PollResult<string>>
Polls for changes to the frontend base URL. Behavior:
  • Periodically checks alias availability (every 1 hour)
  • Falls back to https://botnadzor.org if no aliases are available
Source: src/entrypoints/background/@services/frontend-service.ts:15-92

​
InspectorService

Manages the account inspection UI, which displays account activity and allows reporting suspicious accounts. Dependencies:
  • AuthService
  • NotificationService
  • VkDomainResolver
Key Methods: 
async trigger(
  contentId: ContentId,
  payload: InspectorInstancePayload | undefined
): Promise<void>
Opens the inspector for a specific account, or closes it if payload is undefined. 
async setTab(
  contentId: ContentId,
  tab: "activity" | "report"
): Promise<void>
Switches between activity and report tabs. 
async reinspectAccount(vkDomain: VkDomain): Promise<ResultOfInspectAccount>
Fetches fresh account inspection data from the API. 
async getAccountInspection(vkDomain: VkDomain): Promise<ResultOfInspectAccount>
Returns cached or fresh inspection data. 
async submitReport(payload: {
  tagSuggestion: TagSuggestion;
  text: string;
  trigger: InspectorTrigger;
  vkDomain: VkDomain;
}): Promise<ResultOfReportAccount>
Submits an account report to the Botnadzor API. Source: src/entrypoints/background/@services/inspector-service.ts:54-321

​
NotificationService

Manages in-page notifications and global notification state (welcome messages, announcements). Dependencies: None Key Methods: 
async trigger(
  contentId: ContentId,
  payload: TriggeredNotificationPayload | undefined
): Promise<void>
Triggers or dismisses a notification for a specific content ID. 
markWelcomeAnnouncementAsShown(): void
Marks the welcome announcement as shown. 
markWelcomeAnnouncementAsRead(): void
Marks the welcome announcement as read. 
markAnnouncementAsRead(createdAt: IsoDateTime): void
Marks a specific announcement as read. 
async pollGlobalNotificationsState(
  lastPollVersion: PollVersion | undefined
): Promise<PollResult<GlobalNotificationsState>>
Polls for changes to global notification state. Source: src/entrypoints/background/@services/notification-service.ts:62-190

​
PopupService

Manages the extension popup state, including active tab. Dependencies: None Key Methods: 
getActiveTab(): PopupTab
Returns the currently active tab. 
setActiveTab(tab: PopupTab): void
Sets the active tab. 
open({ tab }: { tab?: PopupTab }): Promise<void>
Opens the popup, optionally switching to a specific tab. Source: src/entrypoints/background/@services/popup-service.ts:9-36

​
RegDateService

Fetches VK account registration dates from the Botnadzor API. Dependencies:
  • AuthService
  • VkDomainResolver
Key Methods: 
async obtain(vkDomain: VkDomain): Promise<RegDateInfo>
Fetches registration date for a VK account. Results are cached (LRU cache with max 1000 entries). Return Type: 
type RegDateInfo = DynamicApiEndpointOutcome<"getRegDate"> & {
  checkedAt: IsoDateTime;
};
Error Cases:
  • Invalid VK domain
  • Communities (negative VK IDs) are not supported
  • Missing authentication
  • Missing permission (getRegDate)
Source: src/entrypoints/background/@services/reg-date-service.ts:32-144

​
RootConfigService

Fetches and caches the root configuration from the static API, which includes extension version ranges and remote system URLs. Dependencies:
  • AliasManager (for static API)
Key Methods: 
async get(): Promise<RootConfig>
Returns the current root config (with 2-second timeout). 
async poll(
  lastPollVersion: PollVersion | undefined
): Promise<PollResult<RootConfig>>
Polls for changes to root config. 
async getExtensionVersionRange(): Promise<SemverRange>
Returns the supported extension version range. Behavior:
  • Fetches from /root-config.json
  • Retries up to 3 times on failure
  • Minimum 30-minute interval between successful fetches
  • Falls back to seed config on parse errors
Source: src/entrypoints/background/@services/root-config-service.ts:27-188

​
StaticListsService

Manages static data lists (accounts, tags, walls, announcements, insertions) with local/remote combining modes. Dependencies:
  • AliasManager (for static API)
  • RootConfigService
Key Methods:

​
Reading Items

async getItems<ListId extends StaticListId>(
  listId: ListId
): Promise<Array<StaticListItem<ListId>>>
Returns all items for a list (respects combining mode). 
async findItem<ListId extends StaticListId, Index extends keyof Item>(
  listId: ListId,
  index: Index,
  value: Item[Index],
  options?: { origin?: "remote" | "local" }
): Promise<StaticListItem<ListId> | undefined>
Finds a single item by index. 
async getItemsPage(
  listId: StaticListId,
  params: { offset: number; limit: number }
): Promise<{ items: Array<...>; totalCount: number }>
Returns a paginated list of items. 
async searchItems(
  listId: StaticListId,
  params: { index: string; value: unknown }
): Promise<{ items: Array<...> }>
Searches for items by index value.

​
Managing Local Items

async addLocalItem<ListId extends StaticListId>(
  listId: ListId,
  item: StaticListItem<ListId>
): Promise<void>
Adds a local item. 
async putLocalItem<ListId extends StaticListId>(
  listId: ListId,
  item: StaticListItem<ListId>
): Promise<void>
Replaces an existing local item. 
async removeLocalItem<ListId extends StaticListId, Index extends keyof Item>(
  listId: ListId,
  index: Index,
  value: Item[Index]
): Promise<{ deletedCount: number }>
Removes a local item.

​
Metadata & Configuration

async getListSummary(listId: StaticListId): Promise<StaticListSummary>
Returns list summary (item counts, timestamps). 
async getCombiningMode(listId: StaticListId): Promise<StaticListCombiningMode>
Returns the combining mode: "remoteOnly", "localOnly", or "remoteWithLocalOverrides". 
async setCombiningMode(
  listId: StaticListId,
  mode: StaticListCombiningMode
): Promise<void>
Sets the combining mode. 
updateIfNeeded(payload?: {
  listIds?: StaticListId[];
  toleranceInMinutes?: number;
}): void
Triggers list updates if they’re outdated. Data Storage:
  • Remote lists stored in IndexedDB with dual-instance swapping
  • Local items stored in separate tables
  • Combining modes determine which data is visible
Source: src/entrypoints/background/@services/static-lists-service.ts:180-1501

​
UserConfigService

Manages user preferences, including tag color overrides and comment collection settings. Dependencies: None Key Methods: 
async get(): Promise<UserConfig>
Returns current user configuration. 
set(newValue: UserConfig): void
Updates user configuration. 
async poll(
  lastPollVersion: PollVersion | undefined
): Promise<PollResult<UserConfig>>
Polls for configuration changes. UserConfig Type: 
type UserConfig = {
  tagOverrideLookup: Record<string, {
    colorForHighlight?: HexColor;
    hidden?: true;
  }>;
  fansDisplay: "default" | "table";
  collectingComments?: true;
};
Source: src/entrypoints/background/@services/user-config-service.ts:24-76

Build docs developers (and LLMs) love

Get started for freeTalk to us