@bbloker/sdk 0.1.0

package/dist/chunk-KT5GDIXH.cjs

@@ -0,0 +1,422 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2; var _class3; var _class4;// src/data/default-rules.json
+var default_rules_default = {
+  version: 1,
+  updatedAt: "2026-02-06",
+  blockedUAs: [
+    "GPTBot",
+    "ChatGPT-User",
+    "OAI-SearchBot",
+    "CCBot",
+    "anthropic-ai",
+    "ClaudeBot",
+    "Claude-Web",
+    "Meta-ExternalAgent",
+    "Meta-ExternalFetcher",
+    "FacebookBot",
+    "facebookexternalhit",
+    "PerplexityBot",
+    "Bytespider",
+    "Google-Extended",
+    "Applebot-Extended",
+    "cohere-ai",
+    "Diffbot",
+    "ImagesiftBot",
+    "Omgilibot",
+    "Omgili",
+    "YouBot",
+    "Amazonbot",
+    "AI2Bot",
+    "Ai2Bot-Dolma",
+    "Scrapy",
+    "PetalBot",
+    "Semrushbot",
+    "AhrefsBot",
+    "MJ12bot",
+    "DotBot",
+    "Seekport",
+    "BLEXBot",
+    "DataForSeoBot",
+    "magpie-crawler",
+    "Timpibot",
+    "Velenpublicwebcrawler",
+    "Webzio-Extended",
+    "iaskspider",
+    "Kangaroo Bot",
+    "img2dataset"
+  ],
+  blockedIPs: [
+    "20.15.240.0/20",
+    "20.171.206.0/23",
+    "40.83.2.0/23",
+    "52.230.152.0/21",
+    "20.171.207.0/24"
+  ],
+  headerPatterns: [
+    {
+      name: "accept",
+      pattern: "^\\*\\/\\*$",
+      weight: 0.3
+    },
+    {
+      name: "accept-language",
+      pattern: "^$",
+      weight: 0.5
+    },
+    {
+      name: "accept-encoding",
+      pattern: "^$",
+      weight: 0.4
+    }
+  ],
+  anomalyThreshold: 0.7
+};
+
+// src/core/logger.ts
+var LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4
+};
+var Logger = (_class = class {constructor() { _class.prototype.__init.call(this); }
+  __init() {this.level = LEVELS.warn}
+  setLevel(level) {
+    this.level = LEVELS[level];
+  }
+  debug(...args) {
+    if (this.level <= LEVELS.debug) console.debug("[bbloker]", ...args);
+  }
+  info(...args) {
+    if (this.level <= LEVELS.info) console.info("[bbloker]", ...args);
+  }
+  warn(...args) {
+    if (this.level <= LEVELS.warn) console.warn("[bbloker]", ...args);
+  }
+  error(...args) {
+    if (this.level <= LEVELS.error) console.error("[bbloker]", ...args);
+  }
+}, _class);
+var logger = new Logger();
+
+// src/core/rules.ts
+var RuleManager = (_class2 = class {
+  
+  
+  
+  __init2() {this.syncTimer = null}
+  // Pre-compiled UA patterns for fast matching
+  __init3() {this.uaPatterns = []}
+  constructor(config) {;_class2.prototype.__init2.call(this);_class2.prototype.__init3.call(this);
+    this.apiUrl = config.apiUrl;
+    this.apiKey = config.apiKey;
+    this.rules = default_rules_default;
+    this.compilePatterns();
+    this.sync();
+    this.syncTimer = setInterval(() => this.sync(), config.syncInterval);
+    if (_optionalChain([this, 'access', _ => _.syncTimer, 'optionalAccess', _2 => _2.unref])) {
+      this.syncTimer.unref();
+    }
+  }
+  compilePatterns() {
+    this.uaPatterns = this.rules.blockedUAs.map((ua) => ua.toLowerCase());
+  }
+  get current() {
+    return this.rules;
+  }
+  /** Check if a User-Agent matches any blocked pattern */
+  isBlockedUA(ua) {
+    const lower = ua.toLowerCase();
+    return this.uaPatterns.some((pattern) => lower.includes(pattern));
+  }
+  /** Check if an IP is in any blocked CIDR range */
+  isBlockedIP(ip) {
+    return this.rules.blockedIPs.some((cidr) => ipInCidr(ip, cidr));
+  }
+  /** Calculate header anomaly score (0-1) */
+  headerAnomalyScore(headers) {
+    let totalWeight = 0;
+    let matchWeight = 0;
+    for (const pattern of this.rules.headerPatterns) {
+      totalWeight += pattern.weight;
+      const value = _nullishCoalesce(headers[pattern.name.toLowerCase()], () => ( ""));
+      try {
+        if (new RegExp(pattern.pattern).test(value)) {
+          matchWeight += pattern.weight;
+        }
+      } catch (e) {
+      }
+    }
+    return totalWeight > 0 ? matchWeight / totalWeight : 0;
+  }
+  get anomalyThreshold() {
+    return this.rules.anomalyThreshold;
+  }
+  async sync() {
+    try {
+      const res = await fetch(`${this.apiUrl}/v1/rules`, {
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!res.ok) {
+        logger.warn(`bbloker: rule sync failed: ${res.status}`);
+        return;
+      }
+      const data = await res.json();
+      if (data.version > this.rules.version) {
+        this.rules = data;
+        this.compilePatterns();
+        logger.info(`bbloker: rules updated to v${data.version}`);
+      }
+    } catch (e2) {
+      logger.debug("bbloker: rule sync error (using cached rules)");
+    }
+  }
+  destroy() {
+    if (this.syncTimer) {
+      clearInterval(this.syncTimer);
+      this.syncTimer = null;
+    }
+  }
+}, _class2);
+function ipToLong(ip) {
+  const parts = ip.split(".");
+  if (parts.length !== 4) return 0;
+  return (parseInt(parts[0], 10) << 24 | parseInt(parts[1], 10) << 16 | parseInt(parts[2], 10) << 8 | parseInt(parts[3], 10)) >>> 0;
+}
+function ipInCidr(ip, cidr) {
+  if (ip.includes(":")) return false;
+  const [range, bits] = cidr.split("/");
+  if (!range || !bits) return false;
+  const mask = ~(2 ** (32 - parseInt(bits, 10)) - 1) >>> 0;
+  const ipLong = ipToLong(ip);
+  const rangeLong = ipToLong(range);
+  return (ipLong & mask) === (rangeLong & mask);
+}
+
+// src/core/rate-limiter.ts
+var RateLimiter = (_class3 = class {
+  __init4() {this.windows = /* @__PURE__ */ new Map()}
+  
+  
+  __init5() {this.cleanupTimer = null}
+  constructor(maxRequests, windowMs) {;_class3.prototype.__init4.call(this);_class3.prototype.__init5.call(this);
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+    this.cleanupTimer = setInterval(() => this.cleanup(), 6e4);
+    if (_optionalChain([this, 'access', _3 => _3.cleanupTimer, 'optionalAccess', _4 => _4.unref])) {
+      this.cleanupTimer.unref();
+    }
+  }
+  /** Returns true if the IP has exceeded the rate limit */
+  isExceeded(ip) {
+    const now = Date.now();
+    const window = this.windows.get(ip);
+    if (!window || now > window.resetAt) {
+      this.windows.set(ip, { count: 1, resetAt: now + this.windowMs });
+      return false;
+    }
+    window.count++;
+    return window.count > this.maxRequests;
+  }
+  cleanup() {
+    const now = Date.now();
+    for (const [ip, window] of this.windows) {
+      if (now > window.resetAt) {
+        this.windows.delete(ip);
+      }
+    }
+  }
+  destroy() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.windows.clear();
+  }
+}, _class3);
+
+// src/core/telemetry.ts
+var Telemetry = (_class4 = class {
+  __init6() {this.buffer = []}
+  
+  
+  
+  __init7() {this.flushTimer = null}
+  
+  constructor(config) {;_class4.prototype.__init6.call(this);_class4.prototype.__init7.call(this);
+    this.apiUrl = config.apiUrl;
+    this.apiKey = config.apiKey;
+    this.maxBuffer = config.bufferSize;
+    this.enabled = config.enabled;
+    if (!this.enabled) return;
+    this.flushTimer = setInterval(() => this.flush(), config.flushInterval);
+    if (_optionalChain([this, 'access', _5 => _5.flushTimer, 'optionalAccess', _6 => _6.unref])) {
+      this.flushTimer.unref();
+    }
+  }
+  push(fp) {
+    if (!this.enabled) return;
+    this.buffer.push(fp);
+    if (this.buffer.length >= this.maxBuffer) {
+      this.flush();
+    }
+  }
+  async flush() {
+    if (this.buffer.length === 0) return;
+    const batch = this.buffer.splice(0);
+    try {
+      const res = await fetch(`${this.apiUrl}/v1/fingerprints`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ events: batch }),
+        signal: AbortSignal.timeout(5e3)
+      });
+      if (!res.ok) {
+        logger.warn(`bbloker: telemetry flush failed: ${res.status}`);
+      } else {
+        logger.debug(`bbloker: flushed ${batch.length} fingerprints`);
+      }
+    } catch (e3) {
+      logger.debug(`bbloker: telemetry flush error (silent)`);
+    }
+  }
+  destroy() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    this.buffer = [];
+  }
+}, _class4);
+
+// src/core/engine.ts
+var DEFAULTS = {
+  apiUrl: "https://api.bbloker.com",
+  syncInterval: 3e5,
+  flushInterval: 1e4,
+  bufferSize: 100,
+  telemetry: true,
+  rateLimit: 60,
+  rateLimitWindow: 6e4,
+  logLevel: "warn"
+};
+var Bbloker = class {
+  
+  
+  
+  
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("bbloker: apiKey is required");
+    }
+    const apiUrl = _nullishCoalesce(config.apiUrl, () => ( DEFAULTS.apiUrl));
+    const syncInterval = _nullishCoalesce(config.syncInterval, () => ( DEFAULTS.syncInterval));
+    const flushInterval = _nullishCoalesce(config.flushInterval, () => ( DEFAULTS.flushInterval));
+    const bufferSize = _nullishCoalesce(config.bufferSize, () => ( DEFAULTS.bufferSize));
+    const telemetryEnabled = _nullishCoalesce(config.telemetry, () => ( DEFAULTS.telemetry));
+    const rateLimit = _nullishCoalesce(config.rateLimit, () => ( DEFAULTS.rateLimit));
+    const rateLimitWindow = _nullishCoalesce(config.rateLimitWindow, () => ( DEFAULTS.rateLimitWindow));
+    const logLevel = _nullishCoalesce(config.logLevel, () => ( DEFAULTS.logLevel));
+    this.config = {
+      apiKey: config.apiKey,
+      apiUrl,
+      rateLimit,
+      rateLimitWindow,
+      logLevel,
+      onBlock: config.onBlock
+    };
+    logger.setLevel(logLevel);
+    this.rules = new RuleManager({
+      apiUrl,
+      apiKey: config.apiKey,
+      syncInterval
+    });
+    this.rateLimiter = new RateLimiter(rateLimit, rateLimitWindow);
+    this.telemetry = new Telemetry({
+      apiUrl,
+      apiKey: config.apiKey,
+      flushInterval,
+      bufferSize,
+      enabled: telemetryEnabled
+    });
+    logger.info("bbloker: initialized");
+  }
+  /**
+   * Analyze a normalized request and return a block/allow decision.
+   * This is the core method — adapters call this.
+   */
+  analyze(req) {
+    if (req.userAgent && this.rules.isBlockedUA(req.userAgent)) {
+      const decision2 = {
+        action: "block",
+        reason: "known_bot_ua",
+        confidence: 0.95
+      };
+      this.report(req, decision2);
+      return decision2;
+    }
+    if (req.ip && this.rules.isBlockedIP(req.ip)) {
+      const decision2 = {
+        action: "block",
+        reason: "known_bot_ip",
+        confidence: 0.9
+      };
+      this.report(req, decision2);
+      return decision2;
+    }
+    if (req.ip && this.rateLimiter.isExceeded(req.ip)) {
+      const decision2 = {
+        action: "block",
+        reason: "rate_limit",
+        confidence: 0.7
+      };
+      this.report(req, decision2);
+      return decision2;
+    }
+    const anomalyScore = this.rules.headerAnomalyScore(req.headers);
+    if (anomalyScore > this.rules.anomalyThreshold) {
+      const decision2 = {
+        action: "block",
+        reason: "header_anomaly",
+        confidence: anomalyScore
+      };
+      this.report(req, decision2);
+      return decision2;
+    }
+    const decision = { action: "allow" };
+    this.report(req, decision);
+    return decision;
+  }
+  report(req, decision) {
+    const fp = {
+      ip: req.ip,
+      userAgent: req.userAgent,
+      headerOrder: req.headerNames,
+      headers: req.headers,
+      path: req.path,
+      method: req.method,
+      ts: Date.now()
+    };
+    this.telemetry.push(fp);
+    if (decision.action === "block") {
+      logger.debug(
+        `bbloker: blocked ${req.ip} [${decision.reason}] UA="${req.userAgent.slice(0, 80)}"`
+      );
+    }
+  }
+  /** Clean up timers. Call when shutting down. */
+  destroy() {
+    this.rules.destroy();
+    this.rateLimiter.destroy();
+    this.telemetry.destroy();
+    logger.info("bbloker: destroyed");
+  }
+};
+
+
+
+exports.Bbloker = Bbloker;

package/dist/index.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
+
+var _chunkKT5GDIXHcjs = require('./chunk-KT5GDIXH.cjs');
+
+
+exports.Bbloker = _chunkKT5GDIXHcjs.Bbloker;

package/dist/index.d.cts

@@ -0,0 +1,94 @@
+interface BblokerConfig {
+    /** API key from bbloker dashboard (bb-sk-xxx) */
+    apiKey: string;
+    /** API endpoint. Default: https://api.bbloker.com */
+    apiUrl?: string;
+    /** Rule sync interval in ms. Default: 300_000 (5 min) */
+    syncInterval?: number;
+    /** Telemetry flush interval in ms. Default: 10_000 (10s) */
+    flushInterval?: number;
+    /** Max fingerprints to buffer before force flush. Default: 100 */
+    bufferSize?: number;
+    /** Enable telemetry reporting. Default: true */
+    telemetry?: boolean;
+    /** Rate limit: max requests per IP per window. Default: 60 */
+    rateLimit?: number;
+    /** Rate limit window in ms. Default: 60_000 (1 min) */
+    rateLimitWindow?: number;
+    /** Custom action on block. Default: return 403 */
+    onBlock?: (ctx: BlockContext) => void | Response | Promise<void | Response>;
+    /** Log level. Default: 'warn' */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+}
+interface Fingerprint {
+    /** Client IP */
+    ip: string;
+    /** Raw User-Agent */
+    userAgent: string;
+    /** Ordered list of header names */
+    headerOrder: string[];
+    /** Key headers for anomaly detection */
+    headers: Record<string, string>;
+    /** Request path */
+    path: string;
+    /** HTTP method */
+    method: string;
+    /** Timestamp */
+    ts: number;
+}
+interface Decision {
+    action: 'allow' | 'block';
+    reason?: string;
+    /** Confidence 0-1 */
+    confidence?: number;
+}
+interface BlockContext {
+    fingerprint: Fingerprint;
+    decision: Decision;
+}
+interface RuleSet {
+    version: number;
+    updatedAt: string;
+    /** User-Agent substrings to block */
+    blockedUAs: string[];
+    /** CIDR ranges to block */
+    blockedIPs: string[];
+    /** Known bot header patterns */
+    headerPatterns: HeaderPattern[];
+    /** Header anomaly threshold (0-1). Above = block */
+    anomalyThreshold: number;
+}
+interface HeaderPattern {
+    /** Header name to check */
+    name: string;
+    /** Regex pattern that indicates bot */
+    pattern: string;
+    /** Weight for anomaly scoring */
+    weight: number;
+}
+interface NormalizedRequest {
+    ip: string;
+    userAgent: string;
+    headers: Record<string, string>;
+    headerNames: string[];
+    path: string;
+    method: string;
+}
+
+declare class Bbloker {
+    private rules;
+    private rateLimiter;
+    private telemetry;
+    private config;
+    constructor(config: BblokerConfig);
+    /**
+     * Analyze a normalized request and return a block/allow decision.
+     * This is the core method — adapters call this.
+     */
+    analyze(req: NormalizedRequest): Decision;
+    private report;
+    /** Clean up timers. Call when shutting down. */
+    destroy(): void;
+}
+
+export { Bbloker, type BblokerConfig, type BlockContext, type Decision, type Fingerprint, type NormalizedRequest, type RuleSet };

package/dist/index.d.ts

@@ -0,0 +1,94 @@
+interface BblokerConfig {
+    /** API key from bbloker dashboard (bb-sk-xxx) */
+    apiKey: string;
+    /** API endpoint. Default: https://api.bbloker.com */
+    apiUrl?: string;
+    /** Rule sync interval in ms. Default: 300_000 (5 min) */
+    syncInterval?: number;
+    /** Telemetry flush interval in ms. Default: 10_000 (10s) */
+    flushInterval?: number;
+    /** Max fingerprints to buffer before force flush. Default: 100 */
+    bufferSize?: number;
+    /** Enable telemetry reporting. Default: true */
+    telemetry?: boolean;
+    /** Rate limit: max requests per IP per window. Default: 60 */
+    rateLimit?: number;
+    /** Rate limit window in ms. Default: 60_000 (1 min) */
+    rateLimitWindow?: number;
+    /** Custom action on block. Default: return 403 */
+    onBlock?: (ctx: BlockContext) => void | Response | Promise<void | Response>;
+    /** Log level. Default: 'warn' */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+}
+interface Fingerprint {
+    /** Client IP */
+    ip: string;
+    /** Raw User-Agent */
+    userAgent: string;
+    /** Ordered list of header names */
+    headerOrder: string[];
+    /** Key headers for anomaly detection */
+    headers: Record<string, string>;
+    /** Request path */
+    path: string;
+    /** HTTP method */
+    method: string;
+    /** Timestamp */
+    ts: number;
+}
+interface Decision {
+    action: 'allow' | 'block';
+    reason?: string;
+    /** Confidence 0-1 */
+    confidence?: number;
+}
+interface BlockContext {
+    fingerprint: Fingerprint;
+    decision: Decision;
+}
+interface RuleSet {
+    version: number;
+    updatedAt: string;
+    /** User-Agent substrings to block */
+    blockedUAs: string[];
+    /** CIDR ranges to block */
+    blockedIPs: string[];
+    /** Known bot header patterns */
+    headerPatterns: HeaderPattern[];
+    /** Header anomaly threshold (0-1). Above = block */
+    anomalyThreshold: number;
+}
+interface HeaderPattern {
+    /** Header name to check */
+    name: string;
+    /** Regex pattern that indicates bot */
+    pattern: string;
+    /** Weight for anomaly scoring */
+    weight: number;
+}
+interface NormalizedRequest {
+    ip: string;
+    userAgent: string;
+    headers: Record<string, string>;
+    headerNames: string[];
+    path: string;
+    method: string;
+}
+
+declare class Bbloker {
+    private rules;
+    private rateLimiter;
+    private telemetry;
+    private config;
+    constructor(config: BblokerConfig);
+    /**
+     * Analyze a normalized request and return a block/allow decision.
+     * This is the core method — adapters call this.
+     */
+    analyze(req: NormalizedRequest): Decision;
+    private report;
+    /** Clean up timers. Call when shutting down. */
+    destroy(): void;
+}
+
+export { Bbloker, type BblokerConfig, type BlockContext, type Decision, type Fingerprint, type NormalizedRequest, type RuleSet };

package/dist/index.js

@@ -0,0 +1,6 @@
+import {
+  Bbloker
+} from "./chunk-6P6B2RO7.js";
+export {
+  Bbloker
+};