# interrobot-plugin

> Used in the creation of plugins (aka reports) that present data or visualizations for a website in aggregate, across site content. For use with InterroBot application.

Latest version **1.0.0** (published 2026-09-28) · MPL-2.0 license · 0 weekly downloads

## Install

```sh
npm install interrobot-plugin
pnpm add interrobot-plugin
yarn add interrobot-plugin
bun add interrobot-plugin
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-09-28 |
| First published | 2023-12-21 |
| Weekly downloads | 0 |
| License | MPL-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 182.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Ben Caulfield |
| Maintainers | pragmar |
| Keywords | javascript, InterroBot, plugin, webdev, SEO, crawler, spider |

## Links

- npm: https://www.npmjs.com/package/interrobot-plugin
- Repository: https://github.com/interrobot/interrobot-plugin
- Homepage: https://github.com/interrobot/interrobot-plugin#readme
- Issues: https://github.com/interrobot/interrobot-plugin/issues
- npm.io page: https://npm.io/package/interrobot-plugin

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2026-09-28
- 0.18.0 — 2026-02-03
- 0.17.0 — 2025-12-06
- 0.16.0 — 2025-02-06
- 0.15.0 — 2025-02-06
- 0.14.0 — 2024-11-15
- 0.13.0 — 2024-11-11
- 0.12.0 — 2024-10-15
- 0.11.0 — 2024-09-09
- 0.10.0 — 2024-08-15
- 0.9.0 — 2024-03-22
- 0.8.2 — 2024-01-22
- 0.8.1 — 2024-01-03
- 0.8.0 — 2023-12-21

## README

InterroBot plugins transform your web crawler into, well... anything you want. With unrestricted API crawl data access, Interrobot plugins can bring your website analysis concepts to life.

InterroBot plugins are simple HTML/JS/CSS pages that turn crawl data into insights, stunning visualizations, and interactive dashboards. With our flexible API, you can create custom plugins that analyze website content across entire domains, connecting with analytics, LLMs, or your favorite SaaS for deeper insights.

The InterroBot plugin ecosystem is designed for power users. Whether you're building proprietary tools, developing plugins for clients, or contributing to the open-source community, InterroBot plugins adapt to your needs. Available for Windows 10/11, macOS, Linux, and Android, InterroBot plugins are everywhere you need them.

## How Does it Work?

InterroBot hosts an iframe of your webpage and exposes an API from which you can pull data down for analysis.

If you're familiar with vanilla TypeScript or JavaScript, creating a custom plugin script for InterroBot is remarkably straight forward. First you start with a [bare-bones HTML file](https://raw.githubusercontent.com/interrobot/interrobot-plugin/refs/heads/master/examples/vanillajs/basic.html) and a script extending the Plugin base class.
```javascript
// TypeScript vs. JavaScript, both are fine. See examples.
import { Plugin } from "./src/ts/core/plugin";
class BasicExamplePlugin extends Plugin {
    static meta = {
        "title": "Example Plugin",
        "category": "Example",
        "version": "1.0.0",
        "author": "InterroBot",
        "synopsis": `a basic plugin example`,
        "description": `This example is as simple as it gets.`,
    };
    constructor() {
        super();
        // index() has nothing to do with the crawl index, btw. it is
        // the plugin index (think index.html), a view that shows by
        // default, and would generally consist of a form or visualization.
        this.index();
    }
}
// configure to initialize when the page is ready
Plugin.initialize(BasicExamplePlugin);
```

BasicExamplePlugin will not do much at this point, but it will load and run the default `index()` behavior.
You can, of course, override the default `index()` behavior, rendering your page however you wish.
```javascript
protected async index() {

    // add your form and supporting HTML
    this.render(`<div>HTML</div>`);

    // initialize the plugin within InterroBot, from within iframe
    await this.initData({}, []);

    // add handlers to the form
    const button = document.querySelector("button");
    button.addEventListener("click", async (ev) => {
        await this.process(); // where process() is a form handler
    });
}
```

The `process()` method called above would be where you process data. Query the crawl index with
`this.search()`, and stream the results — pagination is handled for you, and you can `break` out
of the loop at any point to stop fetching.
```javascript
protected async process() {

    // queries are exactly as you'd type them into InterroBot search.
    // id and url come with the base model, everything else costs time.
    // here, I just grab the "name" field (the page title)
    const titleWords = new Map();
    for await (const result of this.search("headers: text/html",
        { fields: ["name"], includeExternal: false })) {
        const terms = result.name.trim().split(/[\s\-—]+/g);
        terms.forEach(term => titleWords.set(term,
            (titleWords.get(term) ?? 0) + 1));
    }

    // call for HTML presentation of titleWords with processing complete
    await this.report(titleWords);
}
```

Behind `this.search()` sits the lower-level API: build an `InterroBot.Core.SearchQuery` for any
project, and either stream it (`InterroBot.Core.Search.results(query)`) or run a result handler
callback over it with progress events and result caching (`InterroBot.Core.Search.execute(query,
resultsMap, resultHandler, options)`). `this.search()` is the recommended path; reach for `execute`
when you want cached replay of the result set across reruns of a report.

For working plugins and more ideas getting started, check out the [examples](https://github.com/interrobot/interrobot-plugin/blob/master/examples/) directory.

## What data is available via API?

InterroBot's API provides developers with access to crawled data, enabling analysis and useful customizations. This data allows you to create insightful visualizations, perform complex analysis, or build interactive tools. Whether you're tracking SEO metrics, analyzing content structures, or developing custom reporting tools, our API offers the flexibility and depth you need. Below is an overview of the key data points available, organized by API endpoint:

### GetProjects

Retrieves a list of projects using the Plugin API.

**Optional Fields**

| Field | Description |
|-------|-------------|
| created | ISO 8601 date/time, project created |
| image | datauri of project icon |
| modified | ISO 8601 date/time, project modified |
| urls | Array of URLs configured for project |

### GetResources

Retrieves a list of resources associated with a project using the Plugin API.

**Optional Fields**

| Field | Description |
|-------|-------------|
| assets | array of assets, HTML only |
| content | page/file contents |
| created | ISO 8601 date/time, crawled resource |
| headers | HTTP headers |
| links | array of outlinks, HTML only |
| modified | ISO 8601 date/time, resource modified |
| name | page/file name |
| norobots | crawler indexable |
| origin | forwarding URL, if applicable |
| size | size in bytes |
| status | HTTP status code |
| time | request time, in millis |
| type | resource type, html, pdf, image, etc. |

### GetCrawls

Retrieves a list of crawls using the Plugin API.

**Optional Fields**

| Field | Description |
|-------|-------------|
| created | ISO 8601 date/time, crawl created |
| modified | ISO 8601 date/time, crawl modified |
| report | Crawl details as JSON |
| time | Crawl time in millis |


## Licensing

MPL 2.0. Earlier releases (0.18 and prior) additionally bundled JavaScript to TypeScript ports within `./src/lib` — *Typo.js* ([Modified BSD License](https://raw.githubusercontent.com/cfinke/Typo.js/master/license.txt)) and *Snowball.js* ([MPL 1.1](https://raw.githubusercontent.com/fortnightlabs/snowball-js/master/LICENSE)) — which remain under their original licenses where they appear in release history.

---
_Source: https://npm.io/package/interrobot-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
