@adguard/api NPM

AdGuard API

!NOTE Version: v2.1.0

AdGuard API is a filtering library that provides the following features:

Request and content filtering, using @adguard/tswebextension.
Filtering rules list management (downloading, caching, and auto updates).
Content blocking via AdGuard Assistant UI.
Auto-detecting language filters.
Logging request processing.

AdGuard API

Installation

Install the @adguard/api module via npm or yarn

npm install @adguard/api

yarn add @adguard/api

Import the AdguardApi class to the background script
```
import { AdguardApi } from "@adguard/api";
```
Import adguard-contents at the top of your content script entry
```
import '@adguard/api/content-script';
```
Import adguard-assistant at the top of your assistant script entry
```
import '@adguard/api/assistant';
```

Required web accessible resources

AdGuard API requires web accessible resources from the AdGuard Scriptlets library to be able to redirect web requests to a local "resource" using the $redirect rule modifier. You can use @adguard/tswebextension CLI to download it.

Configuration

Syntax:

type Configuration = {
    filters: number[],
    filteringEnabled: boolean,
    allowlist?: string[],
    blocklist?: string[],
    rules?: string[],
    filtersMetadataUrl: string,
    filterRulesUrl: string,
    documentBlockingPageUrl?: string,
};

Properties:

filters (mandatory) - An array of filters identifiers. You can look for possible filters identifiers in the filters metadata file.
filteringEnabled (mandatory) - Enable/disable filtering engine.
allowlist (optional) - An array of domains, for which AdGuard won't work.
blocklist (optional) - This property completely changes AdGuard behavior. If it is defined, Adguard will work for domains from the blocklist only. All other domains will be ignored. If blocklist is defined, allowlist will be ignored.
rules (optional) - An array of custom filtering rules. Here is an article describing filtering rules syntax. These custom rules might be created by a user via AdGuard Assistant UI.
filtersMetadataUrl (mandatory) - An absolute path to a file, containing filters metadata. Once started, AdGuard will periodically check filters updates by downloading this file. Example: https://filters.adtidy.org/extension/chromium/filters.json.
filterRulesUrl (mandatory) - URL mask used for fetching filters rules. {filter_id} parameter will be replaced with an actual filter identifier. Example: https://filters.adtidy.org/extension/chromium/filters/{filter_id}.txt (English filter (filter id = 2) will be loaded from: https://filters.adtidy.org/extension/chromium/2.txt)
documentBlockingPageUrl (optional) - Path to the document blocking page. If not specified, the default browser page will be shown.

Example:

const configuration: Configuration = {
    filters: [],
    allowlist: [],
    blocklist: [],
    rules: [],
    filtersMetadataUrl: 'https://filters.adtidy.org/extension/chromium/filters.json',
    filterRulesUrl: 'https://filters.adtidy.org/extension/chromium/filters/{filter_id}.txt'
};

Please note, that we do not allow using filters.adtidy.org other than for testing purposes. You have to use your own server for storing filter files. You can (and actually should) use filters.adtidy.org for periodically updating files on your side.

Static methods

Creates a new AdguardApi instance.

`AdguardApi.create`

Syntax:

public static async create(): Promise<AdguardApi>

Example:

const adguardApi = await AdguardApi.create();

Methods

`adguardApi.getMessageHandler`

Gets the message handler for API content script messages.

The API message handler name is a constant that can be exported as MESSAGE_HANDLER_NAME from @adguard/api.

Syntax:

public getMessageHandler(): MessageHandlerMV2

Example:

// get tswebextension message handler
const handleApiMessage = adguardApi.getMessageHandler();

const handleAppMessage = async (message: Message) => {
  // handle your app messages here
};

// route message depending on handler name
browser.runtime.onMessage.addListener(async (message, sender) => {
  if (message?.handlerName === MESSAGE_HANDLER_NAME) {
    return Promise.resolve(handleApiMessage(message, sender));
  }
  return handleAppMessage(message);
});

Returns:

A message handler that will listen to internal messages. For example: messages for get computed css for content-script.

`adguardApi.start`

Initializes AdGuard API and starts it immediately.

Syntax:

public async start(configuration: Configuration): Promise<Configuration>

Example:

const appliedConfiguration = await adguardApi.start(configuration);

Parameters:

configuration - API Configuration

Returns:

A Promise, resolved with applied API Configuration when api is initialized and filtering started

`adguardApi.stop`

Completely stops AdGuard API.

Syntax:

public async stop(): Promise<void>

Example:

await adguardApi.stop();

Returns:

Promise, resolved when API is completely stopped

`adguardApi.configure`

This method modifies AdGuard configuration.

Note, that Adguard must be already started (see adguardApi.start).

Syntax:

public async configure(configuration: Configuration): Promise<Configuration>

Example:

const updatedConfiguration = await adguardApi.configure(configuration);

Parameters:

configuration - API Configuration

Returns:

A Promise object that is getting resolved with applied API Configuration when the API config is updated.

`adguardApi.setFilteringEnabled`

Enables or disables filtering without engine re-initialization.

Syntax:

public async setFilteringEnabled(value: boolean): Promise<void>

Example:

await adguardApi.setFilteringEnabled(false);

Parameters:

value - boolean value that indicates the filtering engine state.

Returns:

A Promise object that is getting resolved when filtering engine state is updated.

`adguardApi.openAssistant`

Opens the AdGuard Assistant UI in the specified tab. You must also subscribe on onAssistantCreateRule event channel for applying rules that are created by Adguard Assistant.

Syntax:

public async openAssistant(tabId: number): Promise<void>

Example:

await adguardApi.openAssistant(tabId);

Parameters:

tabId - chrome.tabs.Tab id, see: https://developer.chrome.com/docs/extensions/reference/tabs/#type-Tab

Returns:

A Promise object that is getting resolved when the Assistant UI is opened in the specified tab.

`adguardApi.closeAssistant`

Closes AdGuard Assistant in the specified tab.

Syntax:

public async openAssistant(tabId: number): Promise<void>

Example:

await adguardApi.closeAssistant(tabId);

Parameters:

tabId - chrome.tabs.Tab id, see: https://developer.chrome.com/docs/extensions/reference/tabs/#type-Tab

Returns:

A Promise object that is getting resolved when Assistant UI id closed in the specified tab.

`adguardApi.getRulesCount`

Gets currently loaded rules count.

Syntax:

public getRulesCount(): number

Example:

adguardApi.getRulesCount();

Returns:

rules count number

`adguardApi.onAssistantCreateRule`

TsWebExtension event channel that receives events when a rule is created via AdGuard Assistant.

Syntax:

public onAssistantCreateRule: EventChannel<string>;

Example:

// update config on Assistant rule apply
const applyRule = async (rule): Promise<void> => {
  console.log(`Rule ${rule} was created by Adguard Assistant`);
  configuration.rules!.push(rule);
  await adguardApi.configure(configuration);
};

// add listener
adguardApi.onAssistantCreateRule.subscribe(applyRule);

// remove listener
adguardApi.onAssistantCreateRule.unsubscribe(applyRule);

`adguardApi.onFiltersDeletion`

TsWebExtension Event channel, which fires event on obsoleted filters deletion. It can be fired after checking an update for filters in the FiltersUpdateService.

Syntax:

public onFiltersDeletion: EventChannel<number[]>;

Example:

// update config on filter deletion
const removeObsoletedFilterId = async (filterIds: number[]): Promise<void> => {
  console.log(`Filters with ids ${filterIds} deleted because they became obsoleted.`);
  configuration.filters = configuration.filters.filter((id) => !filterIds.includes(id));

  await adguardApi.configure(configuration);
};

// add listener
adguardApi.onFiltersDeletion.subscribe(removeObsoletedFilterId);

// remove listener
adguardApi.onFiltersDeletion.unsubscribe(removeObsoletedFilterId);

`adguardApi.onRequestBlocking`

API for adding and removing listeners for request blocking events.

Syntax:

export interface RequestBlockingLoggerInterface {
    addListener(listener: EventChannelListener<RequestBlockingEvent>): void;
    removeListener(listener: EventChannelListener<RequestBlockingEvent>): void;
}

Example:

// Registers an event listener
adguardApi.onRequestBlocked.addListener(
  callback // function, mandatory
)
// Removes specified event listener
adguardApi.onRequestBlocked.removeListener(
  callback // function, mandatory
)

Callback parameter properties:

tabId - Tab identifier.
requestUrl - URL of the blocked request.
referrerUrl - Referrer URL.
rule - Filtering rule that has been applied to this request.
filterId - ID of the filter list the rule belongs to.
requestType - Request mime type. Possible values are listed below:

Request types:
DOCUMENT - top-level frame document.
SUBDOCUMENT - document loaded in a nested frame.
SCRIPT
STYLESHEET
OBJECT
IMAGE
XMLHTTPREQUEST
MEDIA
FONT
WEBSOCKET
OTHER

Usage

See full sample app project in examples/adguard-api

import { AdguardApi, Configuration, RequestBlockingEvent } from "@adguard/api";

(async (): Promise<void> => {
    // create new AdguardApi instance
    const adguardApi = AdguardApi.create();

    const configuration: Configuration = {
        filters: [2],
        allowlist: ["www.example.com"],
        rules: ["example.org##h1"],
        filterRulesUrl: "https://filters.adtidy.org/extension/chromium/filters/{filter_id}.txt",
        filtersMetadataUrl: "https://filters.adtidy.org/extension/chromium/filters.json",
    };

    // console log event on request blocking
    const onRequestBlocked = (event: RequestBlockingEvent) => {
        console.log(event);
    };

    // console log current rules count, loaded in engine
    const logTotalCount = (): void => {
        console.log("Total rules count:", adguardApi.getRulesCount());
    };

    adguardApi.onRequestBlocked.addListener(onRequestBlocked);

    await adguardApi.start(configuration);

    console.log("Finished Adguard API initialization.");
    logTotalCount();

    configuration.allowlist!.push("www.google.com");

    await adguardApi.configure(configuration);

    console.log("Finished Adguard API re-configuration");
    logTotalCount();

    // update config on Assistant rule apply
    adguardApi.onAssistantCreateRule.subscribe(async (rule) => {
        console.log(`Rule ${rule} was created by Adguard Assistant`);
        configuration.rules!.push(rule);
        await adguardApi.configure(configuration);
        console.log("Finished Adguard API re-configuration");
        logTotalCount();
    });

    chrome.runtime.onMessage.addListener(async (message) => {
        switch (message.type) {
            case "OPEN_ASSISTANT": {
                chrome.tabs.query({ active: true }, async (res) => {
                    if (res[0]?.id) {
                        await adguardApi.openAssistant(res[0].id);
                    }
                });
                break;
            }
            default:
            // do nothing
        }
    });

    // Disable Adguard in 1 minute
    setTimeout(async () => {
        adguardApi.onRequestBlocked.removeListener(onRequestBlocked);
        await adguardApi.stop();
        console.log("Adguard API has been disabled.");
    }, 60 * 1000);
})();