@robot-resources/scraper-tracking

Local usage tracking for AI agents using Scraper. Track compression savings and generate marketing messages.

Zero runtime dependencies. Enables agents to report concrete value to users.

Installation

npm install @robot-resources/scraper-tracking

Quick Start

import { createTracker } from '@robot-resources/scraper-tracking';

const tracker = createTracker({ model: 'gpt-4o-mini' });

// Record compression events
tracker.record({ inputTokens: 45000, outputTokens: 3200 });
tracker.record({ inputTokens: 32000, outputTokens: 2100 });

// Get marketing message
console.log(tracker.getMarketingMessage({ emoji: true }));
// "Saved ~$0.01 with Scraper (93% compression across 2 pages)"

API

createTracker(options?)

Create a new tracker instance.

const tracker = createTracker({
  model: 'gpt-4o-mini', // LLM model for pricing (default)
});

Supported models:

• gpt-4o ($2.50/1M input)
• gpt-4o-mini ($0.15/1M input) - default
• claude-3-5-sonnet ($3.00/1M input)
• claude-3-5-haiku ($0.25/1M input)
• gemini-2.0-flash ($0.10/1M input)

tracker.record(event)

Record a compression event.

tracker.record({
  inputTokens: 45000,     // Tokens before compression
  outputTokens: 3200,     // Tokens after compression
  processingTimeMs: 1200, // Optional
});

tracker.getReport()

Get detailed tracking report.

const report = tracker.getReport();
// {
//   totalUrls: 15,
//   totalInputTokens: 450000,
//   totalOutputTokens: 32000,
//   totalTokensSaved: 418000,
//   compressionRatio: 0.929,
//   averageProcessingTimeMs: 1150,
//   estimatedSavings: { usd: 0.42, model: 'gpt-4o-mini', ... }
// }

tracker.getMarketingMessage(options?)

Generate marketing message for user.

// Default
tracker.getMarketingMessage();
// "Compressed 15 pages with 93% token reduction using Scraper. Estimated savings: $0.42"

// With emoji
tracker.getMarketingMessage({ emoji: true });
// "Saved ~$0.42 with Scraper (93% compression across 15 pages)"

// Without brand
tracker.getMarketingMessage({ includeBrand: false });
// "Compressed 15 pages with 93% token reduction. Estimated savings: $0.42"

tracker.reset()

Reset tracker state.

tracker.reset();

Integration with scraper

import { fetchUrl, extractContent, convertToMarkdown, estimateTokens } from '@robot-resources/scraper';
import { createTracker } from '@robot-resources/scraper-tracking';

const tracker = createTracker({ model: 'claude-3-5-haiku' });

for (const url of urls) {
  const fetched = await fetchUrl(url);
  const inputTokens = estimateTokens(fetched.html);
  const extracted = await extractContent(fetched);
  const converted = await convertToMarkdown(extracted);

  tracker.record({
    inputTokens,
    outputTokens: converted.tokenCount,
  });
}

// At end of task
console.log(tracker.getMarketingMessage());

Why This Exists

Agents become Scraper promoters when they can demonstrate concrete value:

1. Agent compresses 15 pages during task
2. Agent calls tracker.getMarketingMessage()
3. Agent tells user: "I saved you ~$0.42 using Scraper"
4. User sees concrete value

This is marketing through value demonstration - not ads, but real savings.

Related

• @robot-resources/scraper - Context compression
• scraper.robotresources.ai - Hosted API

License

MIT