halt-rate 0.2.0 → 0.4.0

package/dist/index.js

@@ -33,7 +33,8 @@ function normalizePolicy(policy) {
     cost: policy.cost ?? 1,
     blockDuration: policy.blockDuration ?? void 0,
     keyExtractor: policy.keyExtractor ?? void 0,
-    exemptions: policy.exemptions ?? []
+    exemptions: policy.exemptions ?? [],
+    plan: policy.plan ?? void 0
   };
   if (normalized.limit <= 0) {
     throw new Error("limit must be positive");
@@ -404,6 +405,25 @@ var RateLimiter = class {
     this.algorithmCache = /* @__PURE__ */ new Map();
     this.otelTracer = options.otelTracer;
     this.metricsRecorder = options.metricsRecorder;
+    this.telemetry = options.telemetry;
+  }
+  /** Fan a finished decision out to the telemetry hooks with rich metadata. */
+  emitTelemetry(request, key, decision, policy, cost) {
+    if (!this.telemetry) return;
+    const metadata = {
+      policy: policy.name,
+      algorithm: policy.algorithm,
+      keyStrategy: policy.keyStrategy,
+      endpoint: extractPath(request) ?? void 0,
+      cost,
+      plan: policy.plan
+    };
+    this.telemetry.onCheck?.(key, decision, metadata);
+    if (decision.allowed) {
+      this.telemetry.onAllowed?.(key, decision, metadata);
+    } else {
+      this.telemetry.onBlocked?.(key, decision, metadata);
+    }
   }
   /**
    * Check if request is allowed under rate limit.
@@ -462,10 +482,12 @@ var RateLimiter = class {
         1
       );
       span2?.end?.();
+      this.emitTelemetry(request, key, decision2, policy, requestCost);
       return decision2;
     }
     const store = this.store;
-    let algorithm = this.algorithmCache.get(policy.name);
+    const cacheKey = `${policy.name}|${policy.algorithm}|${policy.limit}|${policy.window}|${policy.burst}`;
+    let algorithm = this.algorithmCache.get(cacheKey);
     if (!algorithm) {
       if (policy.algorithm === "token_bucket" /* TOKEN_BUCKET */) {
         algorithm = new TokenBucket(policy.burst, policy.limit, policy.window);
@@ -479,7 +501,7 @@ var RateLimiter = class {
       } else {
         throw new Error(`Algorithm ${policy.algorithm} not implemented`);
       }
-      this.algorithmCache.set(policy.name, algorithm);
+      this.algorithmCache.set(cacheKey, algorithm);
     }
     const span = this.otelTracer?.startSpan?.("halt.check", { attributes: { policy: policy.name, key } });
     const state = store.get(storageKey);
@@ -545,6 +567,7 @@ var RateLimiter = class {
       this.metricsRecorder?.("halt.request.blocked", { policy: policy.name }, 1);
     }
     span?.end?.();
+    this.emitTelemetry(request, key, decision, policy, requestCost);
     return decision;
   }
   /**
@@ -1008,6 +1031,7 @@ var GENEROUS_API = {
 };
 var PLAN_FREE = {
   name: "free_plan",
+  plan: "free",
   limit: 100,
   window: 3600,
   // 100 requests per hour
@@ -1017,6 +1041,7 @@ var PLAN_FREE = {
 };
 var PLAN_STARTER = {
   name: "starter_plan",
+  plan: "starter",
   limit: 500,
   window: 3600,
   // 500 requests per hour
@@ -1026,6 +1051,7 @@ var PLAN_STARTER = {
 };
 var PLAN_PRO = {
   name: "pro_plan",
+  plan: "pro",
   limit: 2e3,
   window: 3600,
   // 2000 requests per hour
@@ -1035,6 +1061,7 @@ var PLAN_PRO = {
 };
 var PLAN_BUSINESS = {
   name: "business_plan",
+  plan: "business",
   limit: 5e3,
   window: 3600,
   // 5000 requests per hour
@@ -1044,6 +1071,7 @@ var PLAN_BUSINESS = {
 };
 var PLAN_ENTERPRISE = {
   name: "enterprise_plan",
+  plan: "enterprise",
   limit: 2e4,
   window: 3600,
   // 20000 requests per hour
@@ -1068,11 +1096,611 @@ function getPlanPolicy(planName) {
   return PLAN_TIERS[normalized];
 }
 
+// src/core/registry.ts
+var PolicyRegistry = class {
+  constructor(initial = []) {
+    this.policies = /* @__PURE__ */ new Map();
+    for (const p of initial) this.register(p);
+  }
+  /** Add or replace a policy (keyed by `policy.name`). */
+  register(policy) {
+    this.policies.set(policy.name, policy);
+    return this;
+  }
+  get(name) {
+    return this.policies.get(name);
+  }
+  has(name) {
+    return this.policies.has(name);
+  }
+  /** Mutate fields of an existing policy at runtime (e.g. `{ limit: 500 }`). */
+  update(name, patch) {
+    const existing = this.policies.get(name);
+    if (!existing) throw new Error(`Unknown policy: ${name}`);
+    const updated = { ...existing, ...patch, name: existing.name };
+    if (patch.limit !== void 0 && patch.burst === void 0) {
+      delete updated.burst;
+    }
+    this.policies.set(name, updated);
+    return updated;
+  }
+  remove(name) {
+    return this.policies.delete(name);
+  }
+  list() {
+    return [...this.policies.values()];
+  }
+  /**
+   * Build a resolver for the limiter's `policy` option.
+   * @param selector maps a request to a registered policy name.
+   */
+  resolver(selector) {
+    return (request) => {
+      const name = selector(request);
+      const policy = this.policies.get(name);
+      if (!policy) throw new Error(`Unknown policy: ${name}`);
+      return policy;
+    };
+  }
+};
+function cachedPolicyResolver(loader, options = {}) {
+  const ttlMs = options.ttlMs ?? 5e3;
+  const keyFn = options.key ?? (() => "__default__");
+  const cache = /* @__PURE__ */ new Map();
+  return async (request) => {
+    const key = keyFn(request);
+    const now = Date.now();
+    const hit = cache.get(key);
+    if (hit && hit.expires > now) {
+      return hit.policy;
+    }
+    const policy = await loader(request);
+    cache.set(key, { policy, expires: now + ttlMs });
+    return policy;
+  };
+}
+
+// src/core/quota.ts
+var QuotaPeriod = /* @__PURE__ */ ((QuotaPeriod2) => {
+  QuotaPeriod2["HOURLY"] = "hourly";
+  QuotaPeriod2["DAILY"] = "daily";
+  QuotaPeriod2["MONTHLY"] = "monthly";
+  QuotaPeriod2["YEARLY"] = "yearly";
+  return QuotaPeriod2;
+})(QuotaPeriod || {});
+var QuotaManager = class {
+  constructor(store, telemetry) {
+    this.store = store;
+    this.telemetry = telemetry;
+  }
+  getQuotaKey(identifier, quotaName) {
+    return `halt:quota:${quotaName}:${identifier}`;
+  }
+  calculateResetTime(period) {
+    const now = /* @__PURE__ */ new Date();
+    switch (period) {
+      case "hourly" /* HOURLY */:
+        const nextHour = new Date(now);
+        nextHour.setHours(now.getHours() + 1, 0, 0, 0);
+        return Math.floor(nextHour.getTime() / 1e3);
+      case "daily" /* DAILY */:
+        const nextDay = new Date(now);
+        nextDay.setDate(now.getDate() + 1);
+        nextDay.setHours(0, 0, 0, 0);
+        return Math.floor(nextDay.getTime() / 1e3);
+      case "monthly" /* MONTHLY */:
+        const nextMonth = new Date(now);
+        if (now.getMonth() === 11) {
+          nextMonth.setFullYear(now.getFullYear() + 1, 0, 1);
+        } else {
+          nextMonth.setMonth(now.getMonth() + 1, 1);
+        }
+        nextMonth.setHours(0, 0, 0, 0);
+        return Math.floor(nextMonth.getTime() / 1e3);
+      case "yearly" /* YEARLY */:
+        const nextYear = new Date(now);
+        nextYear.setFullYear(now.getFullYear() + 1, 0, 1);
+        nextYear.setHours(0, 0, 0, 0);
+        return Math.floor(nextYear.getTime() / 1e3);
+      default:
+        throw new Error(`Invalid quota period: ${period}`);
+    }
+  }
+  async getQuota(identifier, quota) {
+    const key = this.getQuotaKey(identifier, quota.name);
+    const stored = await this.store.get(key);
+    if (!stored) {
+      return {
+        name: quota.name,
+        limit: quota.limit,
+        period: quota.period,
+        currentUsage: 0,
+        resetAt: this.calculateResetTime(quota.period)
+      };
+    }
+    const currentQuota = {
+      name: stored.name || quota.name,
+      limit: stored.limit || quota.limit,
+      period: stored.period || quota.period,
+      currentUsage: stored.currentUsage || 0,
+      resetAt: stored.resetAt
+    };
+    const now = Math.floor(Date.now() / 1e3);
+    if (currentQuota.resetAt && now >= currentQuota.resetAt) {
+      currentQuota.currentUsage = 0;
+      currentQuota.resetAt = this.calculateResetTime(currentQuota.period);
+    }
+    return currentQuota;
+  }
+  async checkQuota(identifier, quota, cost = 1) {
+    const currentQuota = await this.getQuota(identifier, quota);
+    const allowed = (currentQuota.currentUsage || 0) + cost <= currentQuota.limit;
+    this.telemetry?.onQuotaCheck?.(identifier, currentQuota, allowed);
+    if (!allowed) {
+      this.telemetry?.onQuotaExceeded?.(identifier, currentQuota);
+    }
+    return { allowed, quota: currentQuota };
+  }
+  async consumeQuota(identifier, quota, cost = 1) {
+    const currentQuota = await this.getQuota(identifier, quota);
+    currentQuota.currentUsage = (currentQuota.currentUsage || 0) + cost;
+    const key = this.getQuotaKey(identifier, quota.name);
+    const ttl = (currentQuota.resetAt || 0) - Math.floor(Date.now() / 1e3) + 3600;
+    await this.store.set(key, currentQuota, ttl);
+    return currentQuota;
+  }
+  async resetQuota(identifier, quota) {
+    const key = this.getQuotaKey(identifier, quota.name);
+    await this.store.delete(key);
+  }
+  remaining(quota) {
+    return Math.max(0, quota.limit - (quota.currentUsage || 0));
+  }
+  isExceeded(quota) {
+    return (quota.currentUsage || 0) >= quota.limit;
+  }
+};
+var QUOTA_FREE_MONTHLY = {
+  name: "free_monthly_requests",
+  limit: 1e4,
+  period: "monthly" /* MONTHLY */
+};
+var QUOTA_PRO_MONTHLY = {
+  name: "pro_monthly_requests",
+  limit: 1e5,
+  period: "monthly" /* MONTHLY */
+};
+var QUOTA_ENTERPRISE_MONTHLY = {
+  name: "enterprise_monthly_requests",
+  limit: 1e6,
+  period: "monthly" /* MONTHLY */
+};
+var QUOTA_FREE_DAILY = {
+  name: "free_daily_requests",
+  limit: 500,
+  period: "daily" /* DAILY */
+};
+var QUOTA_PRO_DAILY = {
+  name: "pro_daily_requests",
+  limit: 5e3,
+  period: "daily" /* DAILY */
+};
+
+// src/core/penalty.ts
+var PenaltyManager = class {
+  constructor(store, config, telemetry) {
+    this.store = store;
+    this.telemetry = telemetry;
+    this.config = {
+      threshold: config?.threshold ?? 10,
+      duration: config?.duration ?? 3600,
+      multiplier: config?.multiplier ?? 0.5,
+      decayRate: config?.decayRate ?? 1
+    };
+  }
+  getPenaltyKey(identifier) {
+    return `halt:penalty:${identifier}`;
+  }
+  async getPenalty(identifier) {
+    const key = this.getPenaltyKey(identifier);
+    const stored = await this.store.get(key);
+    if (!stored) {
+      return {
+        abuseScore: 0,
+        penaltyUntil: null,
+        violations: 0,
+        lastViolation: null
+      };
+    }
+    const penalty = {
+      abuseScore: stored.abuseScore || 0,
+      penaltyUntil: stored.penaltyUntil || null,
+      violations: stored.violations || 0,
+      lastViolation: stored.lastViolation || null
+    };
+    if (penalty.lastViolation) {
+      const hoursElapsed = (Date.now() / 1e3 - penalty.lastViolation) / 3600;
+      const decay = hoursElapsed * this.config.decayRate;
+      penalty.abuseScore = Math.max(0, penalty.abuseScore - decay);
+    }
+    return penalty;
+  }
+  async recordViolation(identifier, severity = 1) {
+    const penalty = await this.getPenalty(identifier);
+    penalty.abuseScore += severity;
+    penalty.violations += 1;
+    penalty.lastViolation = Math.floor(Date.now() / 1e3);
+    let penaltyTriggered = false;
+    if (penalty.abuseScore >= this.config.threshold && !this.isActive(penalty)) {
+      penalty.penaltyUntil = Math.floor(Date.now() / 1e3) + this.config.duration;
+      penaltyTriggered = true;
+    }
+    await this.savePenalty(identifier, penalty);
+    this.telemetry?.onViolation?.(identifier, penalty, severity);
+    if (penaltyTriggered) {
+      this.telemetry?.onPenaltyApplied?.(identifier, penalty);
+    }
+    return penalty;
+  }
+  async applyPenalty(identifier, duration) {
+    const penalty = await this.getPenalty(identifier);
+    penalty.penaltyUntil = Math.floor(Date.now() / 1e3) + (duration ?? this.config.duration);
+    await this.savePenalty(identifier, penalty);
+    this.telemetry?.onPenaltyApplied?.(identifier, penalty);
+    return penalty;
+  }
+  async clearPenalty(identifier) {
+    const key = this.getPenaltyKey(identifier);
+    await this.store.delete(key);
+  }
+  getRateLimitMultiplier(penalty) {
+    if (this.isActive(penalty)) {
+      return this.config.multiplier;
+    }
+    return 1;
+  }
+  isActive(penalty) {
+    if (!penalty.penaltyUntil) {
+      return false;
+    }
+    return Math.floor(Date.now() / 1e3) < penalty.penaltyUntil;
+  }
+  timeRemaining(penalty) {
+    if (!this.isActive(penalty)) {
+      return 0;
+    }
+    return (penalty.penaltyUntil || 0) - Math.floor(Date.now() / 1e3);
+  }
+  async savePenalty(identifier, penalty) {
+    const key = this.getPenaltyKey(identifier);
+    const ttl = 7 * 24 * 3600;
+    await this.store.set(key, penalty, ttl);
+  }
+};
+var PENALTY_LENIENT = {
+  threshold: 20,
+  duration: 1800,
+  // 30 minutes
+  multiplier: 0.75,
+  decayRate: 2
+};
+var PENALTY_MODERATE = {
+  threshold: 10,
+  duration: 3600,
+  // 1 hour
+  multiplier: 0.5,
+  decayRate: 1
+};
+var PENALTY_STRICT = {
+  threshold: 5,
+  duration: 7200,
+  // 2 hours
+  multiplier: 0.25,
+  decayRate: 0.5
+};
+
+// src/core/telemetry.ts
+var LoggingTelemetry = class {
+  constructor(logger = console) {
+    this.logger = logger;
+  }
+  onCheck(key, decision, metadata) {
+    this.logger.debug(
+      `Rate limit check: key=${key}, allowed=${decision.allowed}, remaining=${decision.remaining}, metadata=${JSON.stringify(metadata)}`
+    );
+  }
+  onAllowed(key, decision, _metadata) {
+    this.logger.info(`Request allowed: key=${key}, remaining=${decision.remaining}`);
+  }
+  onBlocked(key, decision, metadata) {
+    this.logger.warn(
+      `Request blocked: key=${key}, retry_after=${decision.retryAfter}s, metadata=${JSON.stringify(metadata)}`
+    );
+  }
+  onQuotaCheck(identifier, quota, allowed) {
+    this.logger.debug(
+      `Quota check: identifier=${identifier}, quota=${quota.name}, allowed=${allowed}, remaining=${quota.limit - (quota.currentUsage || 0)}`
+    );
+  }
+  onQuotaExceeded(identifier, quota) {
+    this.logger.warn(
+      `Quota exceeded: identifier=${identifier}, quota=${quota.name}, limit=${quota.limit}, reset_at=${quota.resetAt}`
+    );
+  }
+  onPenaltyApplied(identifier, penalty) {
+    this.logger.warn(
+      `Penalty applied: identifier=${identifier}, abuse_score=${penalty.abuseScore}, penalty_until=${penalty.penaltyUntil}`
+    );
+  }
+  onViolation(identifier, penalty, severity) {
+    this.logger.info(
+      `Violation recorded: identifier=${identifier}, severity=${severity}, abuse_score=${penalty.abuseScore}, violations=${penalty.violations}`
+    );
+  }
+};
+var MetricsTelemetry = class {
+  constructor(metricsClient) {
+    this.metricsClient = metricsClient;
+  }
+  onCheck(_key, _decision, metadata) {
+    this.metricsClient.increment("halt.checks.total", this.getTags(metadata));
+  }
+  onAllowed(_key, decision, metadata) {
+    this.metricsClient.increment("halt.requests.allowed", this.getTags(metadata));
+    this.metricsClient.gauge("halt.remaining", decision.remaining, this.getTags(metadata));
+  }
+  onBlocked(_key, _decision, metadata) {
+    this.metricsClient.increment("halt.requests.blocked", this.getTags(metadata));
+  }
+  onQuotaCheck(_identifier, quota, _allowed) {
+    const tags = { quota: quota.name, period: quota.period };
+    this.metricsClient.increment("halt.quota.checks", tags);
+    this.metricsClient.gauge(
+      "halt.quota.remaining",
+      quota.limit - (quota.currentUsage || 0),
+      tags
+    );
+  }
+  onQuotaExceeded(_identifier, quota) {
+    const tags = { quota: quota.name, period: quota.period };
+    this.metricsClient.increment("halt.quota.exceeded", tags);
+  }
+  onPenaltyApplied(_identifier, penalty) {
+    this.metricsClient.increment("halt.penalties.applied");
+    this.metricsClient.gauge("halt.penalties.abuse_score", penalty.abuseScore);
+  }
+  onViolation(_identifier, _penalty, severity) {
+    this.metricsClient.increment("halt.violations.total");
+    this.metricsClient.histogram("halt.violations.severity", severity);
+  }
+  getTags(metadata) {
+    if (!metadata) {
+      return {};
+    }
+    return {
+      policy: metadata.policy,
+      algorithm: metadata.algorithm
+    };
+  }
+};
+var CompositeTelemetry = class {
+  constructor(hooks) {
+    this.hooks = hooks;
+  }
+  onCheck(key, decision, metadata) {
+    this.hooks.forEach((hook) => hook.onCheck?.(key, decision, metadata));
+  }
+  onAllowed(key, decision, metadata) {
+    this.hooks.forEach((hook) => hook.onAllowed?.(key, decision, metadata));
+  }
+  onBlocked(key, decision, metadata) {
+    this.hooks.forEach((hook) => hook.onBlocked?.(key, decision, metadata));
+  }
+  onQuotaCheck(identifier, quota, allowed) {
+    this.hooks.forEach((hook) => hook.onQuotaCheck?.(identifier, quota, allowed));
+  }
+  onQuotaExceeded(identifier, quota) {
+    this.hooks.forEach((hook) => hook.onQuotaExceeded?.(identifier, quota));
+  }
+  onPenaltyApplied(identifier, penalty) {
+    this.hooks.forEach((hook) => hook.onPenaltyApplied?.(identifier, penalty));
+  }
+  onViolation(identifier, penalty, severity) {
+    this.hooks.forEach((hook) => hook.onViolation?.(identifier, penalty, severity));
+  }
+};
+
+// src/core/stats.ts
+var StatsCollector = class {
+  constructor(options = {}) {
+    this.allowedTotal = 0;
+    this.blockedTotal = 0;
+    this.byPolicy = /* @__PURE__ */ new Map();
+    this.byEndpoint = /* @__PURE__ */ new Map();
+    this.limitedKeys = /* @__PURE__ */ new Map();
+    this.costByPlan = /* @__PURE__ */ new Map();
+    this.quotaExceededCount = 0;
+    this.penaltiesAppliedCount = 0;
+    this.violationsCount = 0;
+    this.topN = options.topN ?? 20;
+    this.maxTrackedKeys = options.maxTrackedKeys ?? 1e4;
+  }
+  onAllowed(_key, _decision, metadata) {
+    this.allowedTotal++;
+    const cost = Number(metadata?.cost ?? 1);
+    this.policyTally(metadata).allowed++;
+    const endpoint = metadata?.endpoint;
+    if (endpoint) {
+      const e = this.endpointTally(endpoint);
+      e.allowed++;
+      e.cost += cost;
+    }
+    const plan = metadata?.plan ?? metadata?.policy ?? "unknown";
+    this.costByPlan.set(plan, (this.costByPlan.get(plan) ?? 0) + cost);
+  }
+  onBlocked(key, _decision, metadata) {
+    this.blockedTotal++;
+    this.policyTally(metadata).blocked++;
+    const endpoint = metadata?.endpoint;
+    if (endpoint) {
+      this.endpointTally(endpoint).blocked++;
+    }
+    if (key) this.trackLimitedKey(key);
+  }
+  onQuotaExceeded(_identifier, _quota) {
+    this.quotaExceededCount++;
+  }
+  onPenaltyApplied(_identifier, _penalty) {
+    this.penaltiesAppliedCount++;
+  }
+  onViolation(_identifier, _penalty, _severity) {
+    this.violationsCount++;
+  }
+  /** Point-in-time view of the aggregated stats. */
+  snapshot() {
+    const topLimitedKeys = [...this.limitedKeys.entries()].sort((a, b) => b[1] - a[1]).slice(0, this.topN).map(([key, blocked]) => ({ key, blocked }));
+    return {
+      allowedTotal: this.allowedTotal,
+      blockedTotal: this.blockedTotal,
+      byPolicy: mapToObject(this.byPolicy),
+      byEndpoint: mapToObject(this.byEndpoint),
+      topLimitedKeys,
+      costByPlan: mapToObject(this.costByPlan),
+      quotaExceeded: this.quotaExceededCount,
+      penaltiesApplied: this.penaltiesAppliedCount,
+      violations: this.violationsCount,
+      trackedKeys: this.limitedKeys.size
+    };
+  }
+  /** Clear all counters (e.g. after exporting). */
+  reset() {
+    this.allowedTotal = 0;
+    this.blockedTotal = 0;
+    this.byPolicy.clear();
+    this.byEndpoint.clear();
+    this.limitedKeys.clear();
+    this.costByPlan.clear();
+    this.quotaExceededCount = 0;
+    this.penaltiesAppliedCount = 0;
+    this.violationsCount = 0;
+  }
+  policyTally(metadata) {
+    const policy = metadata?.policy ?? "unknown";
+    let t = this.byPolicy.get(policy);
+    if (!t) {
+      t = { allowed: 0, blocked: 0 };
+      this.byPolicy.set(policy, t);
+    }
+    return t;
+  }
+  endpointTally(endpoint) {
+    let e = this.byEndpoint.get(endpoint);
+    if (!e) {
+      e = { allowed: 0, blocked: 0, cost: 0 };
+      this.byEndpoint.set(endpoint, e);
+    }
+    return e;
+  }
+  trackLimitedKey(key) {
+    const current = this.limitedKeys.get(key);
+    if (current !== void 0) {
+      this.limitedKeys.set(key, current + 1);
+      return;
+    }
+    if (this.limitedKeys.size >= this.maxTrackedKeys) {
+      this.evictSmallest();
+    }
+    this.limitedKeys.set(key, 1);
+  }
+  /** Evict the lowest-count tracked key to keep memory bounded. */
+  evictSmallest() {
+    let minKey;
+    let minVal = Infinity;
+    for (const [k, v] of this.limitedKeys) {
+      if (v < minVal) {
+        minVal = v;
+        minKey = k;
+      }
+    }
+    if (minKey !== void 0) this.limitedKeys.delete(minKey);
+  }
+};
+function mapToObject(map) {
+  const out = {};
+  for (const [k, v] of map) out[k] = v;
+  return out;
+}
+
+// src/observability/otel.ts
+var OpenTelemetryMetrics = class {
+  constructor(meter) {
+    this.requests = meter.createCounter("halt.requests", {
+      description: "Total rate-limit checks"
+    });
+    this.blocked = meter.createCounter("halt.blocked", {
+      description: "Rate-limited (blocked) requests"
+    });
+    this.cost = meter.createCounter("halt.cost", {
+      description: "Consumed request cost (weighted endpoints)"
+    });
+    this.quotaExceededCounter = meter.createCounter("halt.quota.exceeded", {
+      description: "Quota-exceeded events"
+    });
+    this.penaltyAppliedCounter = meter.createCounter("halt.penalty.applied", {
+      description: "Penalties applied (abuse controls)"
+    });
+    this.violationsCounter = meter.createCounter("halt.violations", {
+      description: "Recorded abuse violations"
+    });
+  }
+  onAllowed(_key, _decision, metadata) {
+    const policy = String(metadata?.policy ?? "unknown");
+    this.requests.add(1, { policy, allowed: "true" });
+    const endpoint = metadata?.endpoint;
+    const plan = String(metadata?.plan ?? metadata?.policy ?? "unknown");
+    const cost = Number(metadata?.cost ?? 1);
+    this.cost.add(cost, endpoint ? { endpoint: String(endpoint), plan } : { plan });
+  }
+  onBlocked(_key, _decision, metadata) {
+    const policy = String(metadata?.policy ?? "unknown");
+    this.requests.add(1, { policy, allowed: "false" });
+    const endpoint = metadata?.endpoint;
+    this.blocked.add(1, endpoint ? { policy, endpoint: String(endpoint) } : { policy });
+  }
+  onQuotaExceeded(_identifier, quota) {
+    this.quotaExceededCounter.add(1, { quota: quota.name });
+  }
+  onPenaltyApplied(_identifier, _penalty) {
+    this.penaltyAppliedCounter.add(1);
+  }
+  onViolation(_identifier, _penalty, severity) {
+    this.violationsCounter.add(1, { severity });
+  }
+};
+
 exports.Algorithm = Algorithm;
+exports.CompositeTelemetry = CompositeTelemetry;
 exports.InMemoryStore = InMemoryStore;
 exports.KeyStrategy = KeyStrategy;
+exports.LoggingTelemetry = LoggingTelemetry;
+exports.MetricsTelemetry = MetricsTelemetry;
+exports.OpenTelemetryMetrics = OpenTelemetryMetrics;
+exports.PENALTY_LENIENT = PENALTY_LENIENT;
+exports.PENALTY_MODERATE = PENALTY_MODERATE;
+exports.PENALTY_STRICT = PENALTY_STRICT;
+exports.PenaltyManager = PenaltyManager;
+exports.PolicyRegistry = PolicyRegistry;
+exports.QUOTA_ENTERPRISE_MONTHLY = QUOTA_ENTERPRISE_MONTHLY;
+exports.QUOTA_FREE_DAILY = QUOTA_FREE_DAILY;
+exports.QUOTA_FREE_MONTHLY = QUOTA_FREE_MONTHLY;
+exports.QUOTA_PRO_DAILY = QUOTA_PRO_DAILY;
+exports.QUOTA_PRO_MONTHLY = QUOTA_PRO_MONTHLY;
+exports.QuotaManager = QuotaManager;
+exports.QuotaPeriod = QuotaPeriod;
 exports.RateLimiter = RateLimiter;
 exports.RedisStore = RedisStore;
+exports.StatsCollector = StatsCollector;
+exports.cachedPolicyResolver = cachedPolicyResolver;
 exports.extractors = extractors_exports;
 exports.isAtomicStore = isAtomicStore;
 exports.normalizePolicy = normalizePolicy;