extenshi-collector

A production-ready JavaScript library that collects runtime metrics from browser extensions with advanced batching, offline queue management, and automatic retry capabilities. The library is written in TypeScript and can be used either as an npm dependency or via a direct script tag.

Installation

Using npm

npm install extenshi-collector

Using yarn

yarn add extenshi-collector

Usage

As an npm package

import { startCollector } from 'extenshi-collector'
startCollector({ endpoint: 'https://example.com/log' })

Via script tag

Build the project and include dist/index.js in your extension:

<script type="module" src="./dist/index.js"></script>
<script type="module">
  import { startCollector } from './dist/index.js'
  const collector = startCollector({ endpoint: 'https://example.com/log' })
  collector.logCustomEvent('my-event', { foo: 'bar' })
</script>

Or install it through npm:

import { startCollector } from 'collector'
const collector = startCollector({ 
  endpoint: 'https://example.com/log',
  batchSize: 25,
  flushInterval: 3000
})
collector.logCustomEvent('my-event', { foo: 'bar' })

Features

• Automatic Event Collection: Page loads, clicks, errors, and network requests
• Batch Processing: Groups events for efficient network usage (default: 50 events per batch)
• Offline Support: Persists events in IndexedDB when offline, syncs when back online
• Retry Logic: Automatic retry with exponential backoff for failed requests
• Data Sanitization: Automatically redacts sensitive information (emails, tokens, passwords)
• Browser Extension Support: Special handling for Chrome extension environments
• TypeScript Support: Full type definitions included

Configuration Options

interface CollectorConfig {
  endpoint: string           // Required: API endpoint for sending events
  captureConsole?: boolean   // Capture console logs (default: false)
  batchSize?: number         // Events per batch (default: 50)
  flushInterval?: number     // Auto-flush interval in ms (default: 5000)
  maxRetries?: number        // Max retry attempts (default: 3)
  queueConfig?: {
    maxQueueSize?: number    // Max events in queue (default: 1000)
    eventTTL?: number        // Event expiry time (default: 24 hours)
    persistence?: 'memory' | 'localStorage' | 'indexedDB'
  }
}

API Reference

startCollector(config)

Initializes the collector and returns an API object.

const collector = startCollector({
  endpoint: 'https://api.example.com/analytics',
  batchSize: 25,
  flushInterval: 3000
})

collector.logCustomEvent(name, data)

Logs a custom event with optional data.

collector.logCustomEvent('button_click', { 
  buttonId: 'submit',
  page: 'checkout' 
})

collector.flush()

Manually flush all queued events.

await collector.flush()

collector.queueSize()

Returns the current number of queued events.

const pending = collector.queueSize()
console.log(`${pending} events pending`)

Automatic Event Types

The collector automatically captures these events:

• init: When the collector starts (includes browser fingerprint)
• pageload: Page load timing
• click: User clicks (includes target element tag)
• error: JavaScript errors and unhandled promise rejections
• request: Fetch API calls (sanitized request/response data)
• log: Console output (when captureConsole: true)

The collector spawns a worker that listens for initialization, click events, network requests and runtime errors. All events are sanitised before being sent to the provided logging endpoint.

Development

1. Install dependencies with npm install.
2. Build the library using npm run build -w collector.