@rester159/blacktip 0.1.0

package/dist/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export { BlackTip, BlackTipFrame } from './blacktip.js';
+export { BehavioralEngine, HUMAN_PROFILE, SCRAPER_PROFILE } from './behavioral-engine.js';
+export type { MouseStep, KeystrokeStep, ScrollStep, ActionImportance } from './behavioral-engine.js';
+export { DeviceProfileManager } from './fingerprint.js';
+export { generateEvasionScripts } from './evasion.js';
+export { ElementFinder } from './element-finder.js';
+export { Logger } from './logging.js';
+export { BrowserCore } from './browser-core.js';
+export { fitDistribution, fitFittsLaw, fitMouseDynamics, fitTypingDynamics, fitFromSamples, deriveProfileConfig, } from './behavioral/calibration.js';
+export type { MouseSample, MouseMovement, KeystrokeSample, TypingSession, DistributionFit, MouseFit, TypingFit, CalibratedProfile, } from './behavioral/calibration.js';
+export { ProxyPool, ProxyProviders, proxyToUrl } from './proxy-pool.js';
+export type { ProxyDescriptor, ProxyProtocol, PoolOptions } from './proxy-pool.js';
+export { SnapshotManager } from './snapshot.js';
+export type { SessionSnapshot } from './snapshot.js';
+export { attachObservability, JsonlFileExporter, ConsoleExporter, newTraceId, } from './observability.js';
+export type { StructuredEvent, EventExporter } from './observability.js';
+export type { BlackTipConfig, ProfileConfig, DeviceProfile, PluginData, ActionResult, NavigateResult, ScreenshotResult, WaitResult, ActionEvent, BehavioralMetadata, ErrorEvent, RetryEvent, TabChangeEvent, LogEntry, TabInfo, FrameInfo, LogLevel, ClickOptions, TypeOptions, ScrollOptions, HoverOptions, SelectOptions, PressKeyOptions, UploadFileOptions, NavigateOptions, ScreenshotOptions, WaitForOptions, WaitForNavigationOptions, ExtractTextOptions, PageContentOptions, ErrorCode, RetryStrategy, Point, BoundingBox, } from './types.js';
+export { ErrorCodes } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC1F,YAAY,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrG,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EACL,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,WAAW,EACX,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,EACf,QAAQ,EACR,SAAS,EACT,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AACxE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEzE,YAAY,EACV,cAAc,EACd,aAAa,EACb,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,UAAU,EACV,cAAc,EACd,QAAQ,EACR,OAAO,EACP,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,WAAW,EACX,aAAa,EACb,YAAY,EACZ,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,EACT,aAAa,EACb,KAAK,EACL,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+export { BlackTip, BlackTipFrame } from './blacktip.js';
+export { BehavioralEngine, HUMAN_PROFILE, SCRAPER_PROFILE } from './behavioral-engine.js';
+export { DeviceProfileManager } from './fingerprint.js';
+export { generateEvasionScripts } from './evasion.js';
+export { ElementFinder } from './element-finder.js';
+export { Logger } from './logging.js';
+export { BrowserCore } from './browser-core.js';
+// v2 additions — Tier 2 calibration, Tier 3 infrastructure, observability.
+export { fitDistribution, fitFittsLaw, fitMouseDynamics, fitTypingDynamics, fitFromSamples, deriveProfileConfig, } from './behavioral/calibration.js';
+export { ProxyPool, ProxyProviders, proxyToUrl } from './proxy-pool.js';
+export { SnapshotManager } from './snapshot.js';
+export { attachObservability, JsonlFileExporter, ConsoleExporter, newTraceId, } from './observability.js';
+export { ErrorCodes } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE1F,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,2EAA2E;AAC3E,OAAO,EACL,eAAe,EACf,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,GACpB,MAAM,6BAA6B,CAAC;AAYrC,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGxE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,eAAe,EACf,UAAU,GACX,MAAM,oBAAoB,CAAC;AAwC5B,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/logging.d.ts

@@ -0,0 +1,13 @@
+import { EventEmitter } from 'node:events';
+import type { LogLevel } from './types.js';
+export declare class Logger extends EventEmitter {
+    private level;
+    constructor(level?: LogLevel);
+    setLevel(level: LogLevel): void;
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+    private log;
+}
+//# sourceMappingURL=logging.d.ts.map

package/dist/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAY,MAAM,YAAY,CAAC;AASrD,qBAAa,MAAO,SAAQ,YAAY;IACtC,OAAO,CAAC,KAAK,CAAW;gBAEZ,KAAK,GAAE,QAAiB;IAKpC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAI/B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAI5D,OAAO,CAAC,GAAG;CAcZ"}

package/dist/logging.js

@@ -0,0 +1,42 @@
+import { EventEmitter } from 'node:events';
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+export class Logger extends EventEmitter {
+    level;
+    constructor(level = 'info') {
+        super();
+        this.level = level;
+    }
+    setLevel(level) {
+        this.level = level;
+    }
+    debug(message, data) {
+        this.log('debug', message, data);
+    }
+    info(message, data) {
+        this.log('info', message, data);
+    }
+    warn(message, data) {
+        this.log('warn', message, data);
+    }
+    error(message, data) {
+        this.log('error', message, data);
+    }
+    log(level, message, data) {
+        if (LOG_LEVELS[level] < LOG_LEVELS[this.level]) {
+            return;
+        }
+        const entry = {
+            timestamp: new Date().toISOString(),
+            level,
+            message,
+            ...(data !== undefined && { data }),
+        };
+        this.emit('log', entry);
+    }
+}
+//# sourceMappingURL=logging.js.map

package/dist/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,MAAM,OAAO,MAAO,SAAQ,YAAY;IAC9B,KAAK,CAAW;IAExB,YAAY,QAAkB,MAAM;QAClC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,QAAQ,CAAC,KAAe;QACtB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAA8B;QAClD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAA8B;QAClD,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAA8B;QACnD,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAEO,GAAG,CAAC,KAAe,EAAE,OAAe,EAAE,IAA8B;QAC1E,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/C,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAa;YACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,KAAK;YACL,OAAO;YACP,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;SACpC,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/observability.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Observability — structured event schema and reference exporters.
+ *
+ * Design goals:
+ *   1. Every BlackTip event (action, retry, error, tabChange, log) must
+ *      be serializable into a shape that maps 1:1 onto OpenTelemetry
+ *      span attributes, without requiring the OTel SDK as a dependency.
+ *   2. Callers who want OTel can bridge these events into their own
+ *      SDK in ~20 lines.
+ *   3. Callers who just want tail-a-file observability can use the
+ *      built-in JSONL file sink.
+ *
+ * We do NOT ship the OTel SDK because pulling it in would roughly
+ * double the install footprint and most users of BlackTip don't need
+ * it. Instead we define the event schema so bridging is trivial.
+ */
+import type { BlackTip } from './blacktip.js';
+/**
+ * Structured event — the canonical shape every BlackTip event reduces
+ * to when exported. Mirrors OpenTelemetry's span data model loosely:
+ *
+ *   - timestamp: ISO-8601, the event time
+ *   - name: short event name, e.g. "action.click", "retry.strategy"
+ *   - severity: info/warn/error for filtering
+ *   - attributes: flat key-value pairs (values are strings, numbers,
+ *     or booleans — no nested objects, matching OTel's attribute model)
+ *   - traceId: stable per BlackTip session (useful for grouping events
+ *     belonging to one agent flow)
+ *   - spanId: stable per action (groups pre-action, retries, post-action)
+ */
+export interface StructuredEvent {
+    timestamp: string;
+    name: string;
+    severity: 'debug' | 'info' | 'warn' | 'error';
+    attributes: Record<string, string | number | boolean>;
+    traceId: string;
+    spanId?: string;
+}
+/**
+ * 16-char hex trace ID (same format as OpenTelemetry trace IDs, half
+ * the width — enough entropy for a session without a crypto dep).
+ */
+export declare function newTraceId(): string;
+export interface EventExporter {
+    export(event: StructuredEvent): void;
+}
+export declare class JsonlFileExporter implements EventExporter {
+    private path;
+    constructor(path: string);
+    export(event: StructuredEvent): void;
+}
+export declare class ConsoleExporter implements EventExporter {
+    export(event: StructuredEvent): void;
+}
+/**
+ * Wire a BlackTip instance up to one or more StructuredEvent exporters.
+ * Returns an unsubscribe function that removes all listeners added by
+ * this call.
+ *
+ * Usage:
+ *   const stop = attachObservability(bt, [
+ *     new JsonlFileExporter('./events.jsonl'),
+ *     new ConsoleExporter(),
+ *   ]);
+ *   // ... drive BlackTip ...
+ *   stop();
+ */
+export declare function attachObservability(bt: BlackTip, exporters: EventExporter[]): () => void;
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAK9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC9C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;GAGG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAMnC;AAuGD,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACtC;AAID,qBAAa,iBAAkB,YAAW,aAAa;IACzC,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,MAAM;IAIhC,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;CAGrC;AAID,qBAAa,eAAgB,YAAW,aAAa;IACnD,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;CAIrC;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,aAAa,EAAE,GAAG,MAAM,IAAI,CAiCxF"}

package/dist/observability.js

@@ -0,0 +1,189 @@
+/**
+ * Observability — structured event schema and reference exporters.
+ *
+ * Design goals:
+ *   1. Every BlackTip event (action, retry, error, tabChange, log) must
+ *      be serializable into a shape that maps 1:1 onto OpenTelemetry
+ *      span attributes, without requiring the OTel SDK as a dependency.
+ *   2. Callers who want OTel can bridge these events into their own
+ *      SDK in ~20 lines.
+ *   3. Callers who just want tail-a-file observability can use the
+ *      built-in JSONL file sink.
+ *
+ * We do NOT ship the OTel SDK because pulling it in would roughly
+ * double the install footprint and most users of BlackTip don't need
+ * it. Instead we define the event schema so bridging is trivial.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+// ── Trace ID generator ──
+/**
+ * 16-char hex trace ID (same format as OpenTelemetry trace IDs, half
+ * the width — enough entropy for a session without a crypto dep).
+ */
+export function newTraceId() {
+    let s = '';
+    for (let i = 0; i < 16; i++) {
+        s += Math.floor(Math.random() * 16).toString(16);
+    }
+    return s;
+}
+// ── Normalizers: BlackTip event → StructuredEvent ──
+function actionToStructured(ev, traceId) {
+    return {
+        timestamp: ev.timestamp,
+        name: `action.${ev.action}`,
+        severity: ev.outcome === 'success' ? 'info' : 'error',
+        traceId,
+        attributes: {
+            'bt.action': ev.action,
+            'bt.target': ev.target,
+            'bt.outcome': ev.outcome,
+            'bt.duration_ms': ev.duration,
+            'bt.retries': ev.retries,
+            ...(ev.error ? { 'bt.error': ev.error } : {}),
+            ...(ev.value ? { 'bt.value_length': ev.value.length } : {}),
+            ...(ev.behavioral?.mousePathLength ? { 'bt.behavioral.path_length_px': ev.behavioral.mousePathLength } : {}),
+            ...(ev.behavioral?.mouseMoveDuration ? { 'bt.behavioral.move_duration_ms': ev.behavioral.mouseMoveDuration } : {}),
+            ...(ev.behavioral?.preActionPause ? { 'bt.behavioral.pre_pause_ms': ev.behavioral.preActionPause } : {}),
+            ...(ev.behavioral?.postActionPause ? { 'bt.behavioral.post_pause_ms': ev.behavioral.postActionPause } : {}),
+            ...(ev.behavioral?.clickDwell ? { 'bt.behavioral.click_dwell_ms': ev.behavioral.clickDwell } : {}),
+            ...(ev.behavioral?.typingDuration ? { 'bt.behavioral.typing_duration_ms': ev.behavioral.typingDuration } : {}),
+            ...(ev.tabIndex !== undefined ? { 'bt.tab_index': ev.tabIndex } : {}),
+        },
+    };
+}
+function retryToStructured(ev, traceId) {
+    return {
+        timestamp: ev.timestamp,
+        name: 'retry.strategy',
+        severity: 'warn',
+        traceId,
+        attributes: {
+            'bt.action': ev.action,
+            'bt.target': ev.target,
+            'bt.retry.attempt': ev.attempt,
+            'bt.retry.max_attempts': ev.maxAttempts,
+            'bt.retry.strategy': ev.strategy,
+            'bt.error': ev.error,
+        },
+    };
+}
+function errorToStructured(ev, traceId) {
+    return {
+        timestamp: ev.timestamp,
+        name: 'error.action',
+        severity: 'error',
+        traceId,
+        attributes: {
+            'bt.error.code': ev.code,
+            'bt.error.message': ev.message,
+            'bt.error.url': ev.url,
+            'bt.action': ev.action,
+            'bt.attempts': ev.attempts,
+            ...(ev.screenshot ? { 'bt.error.has_screenshot': true, 'bt.error.screenshot_bytes': ev.screenshot.length } : {}),
+        },
+    };
+}
+function tabChangeToStructured(ev, traceId) {
+    return {
+        timestamp: ev.timestamp,
+        name: `tab.${ev.action}`,
+        severity: 'info',
+        traceId,
+        attributes: {
+            'bt.tab.index': ev.tabIndex,
+            'bt.tab.url': ev.url,
+            'bt.tab.action': ev.action,
+        },
+    };
+}
+function logToStructured(entry, traceId) {
+    const attrs = {
+        'bt.log.message': entry.message,
+    };
+    // Flatten data shallow (OTel attrs are flat).
+    if (entry.data) {
+        for (const [k, v] of Object.entries(entry.data)) {
+            if (v === null || v === undefined)
+                continue;
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+                attrs[`bt.log.${k}`] = v;
+            }
+            else {
+                attrs[`bt.log.${k}`] = JSON.stringify(v).slice(0, 200);
+            }
+        }
+    }
+    return {
+        timestamp: entry.timestamp,
+        name: 'log',
+        severity: entry.level,
+        traceId,
+        attributes: attrs,
+    };
+}
+// ── File sink (JSONL) ──
+export class JsonlFileExporter {
+    path;
+    constructor(path) {
+        this.path = path;
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    export(event) {
+        appendFileSync(this.path, JSON.stringify(event) + '\n');
+    }
+}
+// ── Console exporter (for development) ──
+export class ConsoleExporter {
+    export(event) {
+        // eslint-disable-next-line no-console
+        console.log(`[${event.severity}] ${event.name}`, event.attributes);
+    }
+}
+// ── Attach exporters to a BlackTip instance ──
+/**
+ * Wire a BlackTip instance up to one or more StructuredEvent exporters.
+ * Returns an unsubscribe function that removes all listeners added by
+ * this call.
+ *
+ * Usage:
+ *   const stop = attachObservability(bt, [
+ *     new JsonlFileExporter('./events.jsonl'),
+ *     new ConsoleExporter(),
+ *   ]);
+ *   // ... drive BlackTip ...
+ *   stop();
+ */
+export function attachObservability(bt, exporters) {
+    const traceId = newTraceId();
+    const fanOut = (event) => {
+        for (const exporter of exporters) {
+            try {
+                exporter.export(event);
+            }
+            catch {
+                // Swallow exporter errors — observability must never crash the
+                // primary flow.
+            }
+        }
+    };
+    const onAction = (ev) => fanOut(actionToStructured(ev, traceId));
+    const onRetry = (ev) => fanOut(retryToStructured(ev, traceId));
+    const onError = (ev) => fanOut(errorToStructured(ev, traceId));
+    const onTab = (ev) => fanOut(tabChangeToStructured(ev, traceId));
+    const onLog = (entry) => fanOut(logToStructured(entry, traceId));
+    bt.on('action', onAction);
+    bt.on('retry', onRetry);
+    bt.on('error', onError);
+    bt.on('tabChange', onTab);
+    bt.on('log', onLog);
+    return () => {
+        bt.off('action', onAction);
+        bt.off('retry', onRetry);
+        bt.off('error', onError);
+        bt.off('tabChange', onTab);
+        bt.off('log', onLog);
+    };
+}
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"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"}

package/dist/proxy-pool.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Proxy pool abstraction.
+ *
+ * Zero-dependency reference implementation. The caller supplies proxy
+ * credentials; this module handles:
+ *
+ *   - Round-robin or domain-sticky selection.
+ *   - In-memory reputation tracking (which proxies got banned on which
+ *     domains, decay window, avoid-list).
+ *   - URL formatting for the common residential providers (BrightData,
+ *     Oxylabs, Smartproxy, NetNut) — caller passes the provider name
+ *     and credentials, we build the right URL string.
+ *
+ * This is a scaffold — the actual integration with BlackTip's
+ * `BlackTipConfig.proxy` happens when `selectForDomain` is called and
+ * the result is set on the config before `bt.launch()`.
+ *
+ * Residential proxy bandwidth costs money. For the zero-budget path,
+ * callers can instantiate an empty pool and use BlackTip without any
+ * proxy (the default), or plug in a single free datacenter proxy they
+ * already have access to.
+ */
+export type ProxyProtocol = 'http' | 'https' | 'socks5';
+export interface ProxyDescriptor {
+    /** Human-readable ID for logging and reputation tracking. */
+    id: string;
+    protocol: ProxyProtocol;
+    host: string;
+    port: number;
+    username?: string;
+    password?: string;
+    /** Optional: the exit country for this proxy, used for locale/timezone
+     *  consistency checks. */
+    exitCountry?: string;
+    /** Optional: tags like 'residential', 'datacenter', 'mobile'. */
+    tags?: string[];
+}
+/**
+ * Provider-specific URL formatters. The caller provides the API key or
+ * username/password and we produce a ProxyDescriptor ready to use.
+ */
+export declare const ProxyProviders: {
+    readonly brightData: (username: string, password: string, zone: string) => ProxyDescriptor;
+    readonly oxylabs: (username: string, password: string) => ProxyDescriptor;
+    readonly smartproxy: (username: string, password: string) => ProxyDescriptor;
+    readonly custom: (descriptor: ProxyDescriptor) => ProxyDescriptor;
+};
+/**
+ * Format a ProxyDescriptor into the URL string BlackTipConfig.proxy expects.
+ */
+export declare function proxyToUrl(p: ProxyDescriptor): string;
+interface BanRecord {
+    proxyId: string;
+    domain: string;
+    bannedAt: number;
+    reason?: string;
+}
+export interface PoolOptions {
+    /** How long to remember a ban before retrying the same proxy on the
+     *  same domain. Default: 24 hours. */
+    banDecayMs?: number;
+    /** Strategy for picking the next proxy. */
+    strategy?: 'round-robin' | 'random' | 'least-used';
+}
+export declare class ProxyPool {
+    private proxies;
+    private bans;
+    private usageCount;
+    private lastIndexByDomain;
+    private readonly banDecayMs;
+    private readonly strategy;
+    constructor(proxies?: ProxyDescriptor[], options?: PoolOptions);
+    add(proxy: ProxyDescriptor): void;
+    remove(proxyId: string): void;
+    size(): number;
+    /**
+     * Select the next proxy for a given domain, skipping any that are
+     * currently banned on that domain.
+     */
+    selectForDomain(domain: string): ProxyDescriptor | null;
+    /**
+     * Record that a proxy got banned on a domain. Future calls to
+     * `selectForDomain(domain)` will skip this proxy until the ban decays.
+     */
+    reportBan(proxyId: string, domain: string, reason?: string): void;
+    /**
+     * Clear expired bans from the in-memory list. Optional hygiene — not
+     * required for correctness but keeps memory bounded.
+     */
+    pruneExpiredBans(): number;
+    /**
+     * Return a copy of the reputation state for observability.
+     */
+    getReputationSnapshot(): {
+        proxies: ProxyDescriptor[];
+        activeBans: BanRecord[];
+        usage: Record<string, number>;
+    };
+}
+export {};
+//# sourceMappingURL=proxy-pool.d.ts.map

package/dist/proxy-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-pool.d.ts","sourceRoot":"","sources":["../src/proxy-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;8BAC0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc;oCACF,MAAM,YAAY,MAAM,QAAQ,MAAM,KAAG,eAAe;iCAS3D,MAAM,YAAY,MAAM,KAAG,eAAe;oCASvC,MAAM,YAAY,MAAM,KAAG,eAAe;kCAS5C,eAAe,KAAG,eAAe;CAC9C,CAAC;AAEX;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAGrD;AAID,UAAU,SAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B;0CACsC;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,aAAa,GAAG,QAAQ,GAAG,YAAY,CAAC;CACpD;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,IAAI,CAAmB;IAC/B,OAAO,CAAC,UAAU,CAA6B;IAC/C,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;gBAEpD,OAAO,GAAE,eAAe,EAAO,EAAE,OAAO,GAAE,WAAgB;IAMtE,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IAMjC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAI7B,IAAI,IAAI,MAAM;IAId;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAqCvD;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IASjE;;;OAGG;IACH,gBAAgB,IAAI,MAAM;IAO1B;;OAEG;IACH,qBAAqB,IAAI;QAAE,OAAO,EAAE,eAAe,EAAE,CAAC;QAAC,UAAU,EAAE,SAAS,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE;CAQhH"}

package/dist/proxy-pool.js

@@ -0,0 +1,156 @@
+/**
+ * Proxy pool abstraction.
+ *
+ * Zero-dependency reference implementation. The caller supplies proxy
+ * credentials; this module handles:
+ *
+ *   - Round-robin or domain-sticky selection.
+ *   - In-memory reputation tracking (which proxies got banned on which
+ *     domains, decay window, avoid-list).
+ *   - URL formatting for the common residential providers (BrightData,
+ *     Oxylabs, Smartproxy, NetNut) — caller passes the provider name
+ *     and credentials, we build the right URL string.
+ *
+ * This is a scaffold — the actual integration with BlackTip's
+ * `BlackTipConfig.proxy` happens when `selectForDomain` is called and
+ * the result is set on the config before `bt.launch()`.
+ *
+ * Residential proxy bandwidth costs money. For the zero-budget path,
+ * callers can instantiate an empty pool and use BlackTip without any
+ * proxy (the default), or plug in a single free datacenter proxy they
+ * already have access to.
+ */
+/**
+ * Provider-specific URL formatters. The caller provides the API key or
+ * username/password and we produce a ProxyDescriptor ready to use.
+ */
+export const ProxyProviders = {
+    brightData: (username, password, zone) => ({
+        id: `brightdata-${zone}`,
+        protocol: 'http',
+        host: 'brd.superproxy.io',
+        port: 22225,
+        username: `brd-customer-${username}-zone-${zone}`,
+        password,
+        tags: ['residential', 'brightdata'],
+    }),
+    oxylabs: (username, password) => ({
+        id: 'oxylabs',
+        protocol: 'http',
+        host: 'pr.oxylabs.io',
+        port: 7777,
+        username,
+        password,
+        tags: ['residential', 'oxylabs'],
+    }),
+    smartproxy: (username, password) => ({
+        id: 'smartproxy',
+        protocol: 'http',
+        host: 'gate.smartproxy.com',
+        port: 10000,
+        username,
+        password,
+        tags: ['residential', 'smartproxy'],
+    }),
+    custom: (descriptor) => descriptor,
+};
+/**
+ * Format a ProxyDescriptor into the URL string BlackTipConfig.proxy expects.
+ */
+export function proxyToUrl(p) {
+    const auth = p.username && p.password ? `${encodeURIComponent(p.username)}:${encodeURIComponent(p.password)}@` : '';
+    return `${p.protocol}://${auth}${p.host}:${p.port}`;
+}
+export class ProxyPool {
+    proxies = [];
+    bans = [];
+    usageCount = new Map();
+    lastIndexByDomain = new Map();
+    banDecayMs;
+    strategy;
+    constructor(proxies = [], options = {}) {
+        this.proxies = [...proxies];
+        this.banDecayMs = options.banDecayMs ?? 24 * 60 * 60 * 1000;
+        this.strategy = options.strategy ?? 'round-robin';
+    }
+    add(proxy) {
+        if (!this.proxies.find((p) => p.id === proxy.id)) {
+            this.proxies.push(proxy);
+        }
+    }
+    remove(proxyId) {
+        this.proxies = this.proxies.filter((p) => p.id !== proxyId);
+    }
+    size() {
+        return this.proxies.length;
+    }
+    /**
+     * Select the next proxy for a given domain, skipping any that are
+     * currently banned on that domain.
+     */
+    selectForDomain(domain) {
+        if (this.proxies.length === 0)
+            return null;
+        // Filter out proxies banned on this domain (after decay window).
+        const now = Date.now();
+        const banned = new Set(this.bans
+            .filter((b) => b.domain === domain && now - b.bannedAt < this.banDecayMs)
+            .map((b) => b.proxyId));
+        const eligible = this.proxies.filter((p) => !banned.has(p.id));
+        if (eligible.length === 0)
+            return null;
+        let chosen;
+        switch (this.strategy) {
+            case 'random':
+                chosen = eligible[Math.floor(Math.random() * eligible.length)];
+                break;
+            case 'least-used':
+                chosen = eligible.reduce((best, p) => (this.usageCount.get(p.id) ?? 0) < (this.usageCount.get(best.id) ?? 0) ? p : best);
+                break;
+            case 'round-robin':
+            default: {
+                const lastIdx = this.lastIndexByDomain.get(domain) ?? -1;
+                const nextIdx = (lastIdx + 1) % eligible.length;
+                this.lastIndexByDomain.set(domain, nextIdx);
+                chosen = eligible[nextIdx];
+                break;
+            }
+        }
+        this.usageCount.set(chosen.id, (this.usageCount.get(chosen.id) ?? 0) + 1);
+        return chosen;
+    }
+    /**
+     * Record that a proxy got banned on a domain. Future calls to
+     * `selectForDomain(domain)` will skip this proxy until the ban decays.
+     */
+    reportBan(proxyId, domain, reason) {
+        this.bans.push({
+            proxyId,
+            domain,
+            bannedAt: Date.now(),
+            reason,
+        });
+    }
+    /**
+     * Clear expired bans from the in-memory list. Optional hygiene — not
+     * required for correctness but keeps memory bounded.
+     */
+    pruneExpiredBans() {
+        const now = Date.now();
+        const before = this.bans.length;
+        this.bans = this.bans.filter((b) => now - b.bannedAt < this.banDecayMs);
+        return before - this.bans.length;
+    }
+    /**
+     * Return a copy of the reputation state for observability.
+     */
+    getReputationSnapshot() {
+        const now = Date.now();
+        return {
+            proxies: [...this.proxies],
+            activeBans: this.bans.filter((b) => now - b.bannedAt < this.banDecayMs),
+            usage: Object.fromEntries(this.usageCount.entries()),
+        };
+    }
+}
+//# sourceMappingURL=proxy-pool.js.map