@ik-firewall/core 2.3.3 → 2.3.4

package/dist/index.cjs

@@ -50,17 +50,12 @@ module.exports = __toCommonJS(index_exports);
 // src/Registry.ts
 var fs = null;
 var path = null;
-if (typeof window === "undefined") {
-  try {
-  } catch (e) {
-  }
-}
 var Registry = class _Registry {
   static instance;
   registryPath;
   usagePath;
+  hooks;
   hasWarnedNoFs = false;
-  hasWarnedSaveError = false;
   constructor() {
     this.registryPath = "";
     this.usagePath = "";
@@ -72,12 +67,6 @@ var Registry = class _Registry {
         this.usagePath = path.join(process.cwd(), ".ik-adapter", "usage.json");
         this.ensureDirectory();
       } catch (e) {
-        if (!this.hasWarnedNoFs) {
-          console.warn("\n[IK_REGISTRY] \u26A0\uFE0F WARNING: Node.js environment detected but fs/path modules failed to load. Falling back to in-memory mode.");
-          console.warn("[IK_REGISTRY] \u{1F4DD} INTEGRATOR NOTICE: Custom configurations (metaprompts, instances) will be LOST upon server restart or lambda spin-down.");
-          console.warn("[IK_REGISTRY] \u{1F4A1} BEST PRACTICE: Host on a traditional VPS (Node/Docker) or migrate settings to your database if you need persistence on Serverless runtimes.\n");
-          this.hasWarnedNoFs = true;
-        }
       }
     }
   }
@@ -87,23 +76,31 @@ var Registry = class _Registry {
     }
     return _Registry.instance;
   }
+  setHooks(hooks) {
+    this.hooks = hooks;
+  }
   ensureDirectory() {
     if (!fs || !path || !this.registryPath) return;
     try {
       const dir = path.dirname(this.registryPath);
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-      }
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
     } catch (e) {
     }
   }
   /**
-   * Loads all instance configurations from the local registry file.
+   * Loads instance configurations with Hook support
    */
   load() {
-    if (!fs || !this.registryPath) return {};
-    try {
-      if (fs.existsSync(this.registryPath)) {
+    if (this.hooks?.loadState) {
+      try {
+        const hookData = this.hooks.loadState("ik_registry");
+        if (hookData) return JSON.parse(hookData);
+      } catch (e) {
+        console.warn("[IK_REGISTRY] Registry load via hook failed, falling back...");
+      }
+    }
+    if (fs && this.registryPath && fs.existsSync(this.registryPath)) {
+      try {
         const rawData = fs.readFileSync(this.registryPath, "utf8");
         try {
           const decoded = Buffer.from(rawData, "base64").toString("utf8");
@@ -111,69 +108,45 @@ var Registry = class _Registry {
         } catch (e) {
           return JSON.parse(rawData);
         }
+      } catch (error) {
+        console.error("[IK_REGISTRY] Local load error:", error);
       }
-    } catch (error) {
-      console.error("[IK_REGISTRY] Load error:", error);
     }
     return {};
   }
   save(data) {
-    if (!fs || !this.registryPath) {
-      if (!this.hasWarnedNoFs) {
-        console.warn("\n[IK_REGISTRY] \u26A0\uFE0F WARNING: No File System (fs) detected. Running in in-memory mode.");
-        console.warn("[IK_REGISTRY] \u{1F4DD} INTEGRATOR NOTICE: Custom configurations (metaprompts, instances) will be LOST upon server restart or lambda spin-down.");
-        console.warn("[IK_REGISTRY] \u{1F4A1} BEST PRACTICE: If hosting on Vercel/Serverless or Edge runtimes, do not rely on local JSON for dynamic config changes.");
-        console.warn("[IK_REGISTRY] \u{1F449} Consider migrating user-generated adapter settings to your database or host on a traditional VPS (Node/Docker) to ensure persistence.\n");
-        this.hasWarnedNoFs = true;
-      }
-      return;
+    const jsonStr = JSON.stringify(data, null, 2);
+    if (this.hooks?.persistState) {
+      this.hooks.persistState("ik_registry", jsonStr);
     }
-    try {
-      this.ensureDirectory();
-      const jsonStr = JSON.stringify(data, null, 2);
-      const obfuscated = Buffer.from(jsonStr).toString("base64");
-      fs.writeFileSync(this.registryPath, obfuscated, "utf8");
-    } catch (error) {
-      if (!this.hasWarnedSaveError) {
-        console.error("\n[IK_REGISTRY] \u{1F6A8} ERROR saving registry.json. Your environment likely has a read-only filesystem (e.g. Vercel Serverless).");
-        console.error("[IK_REGISTRY] \u{1F4DD} INTEGRATOR NOTICE: Serverless environments wipe or restrict file writes!");
-        console.error("[IK_REGISTRY] \u{1F4A1} BEST PRACTICE: Host on a traditional VPS (Node/Docker) or intercept state changes via Events/Database to ensure persistence.");
-        console.error("[IK_REGISTRY] Actual Error:", error.message, "\n");
-        this.hasWarnedSaveError = true;
+    if (fs && this.registryPath) {
+      try {
+        this.ensureDirectory();
+        const obfuscated = Buffer.from(jsonStr).toString("base64");
+        fs.writeFileSync(this.registryPath, obfuscated, "utf8");
+      } catch (error) {
+        if (!this.hasWarnedNoFs) {
+          console.warn("[IK_REGISTRY] Local write failed (likely Read-Only FS). Relying on hooks/memory.");
+          this.hasWarnedNoFs = true;
+        }
       }
     }
   }
-  /**
-   * Updates a specific instance configuration.
-   */
   updateInstance(instanceId, config) {
     const all = this.load();
-    all[instanceId] = {
-      ...all[instanceId] || {},
-      ...config,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.save(all);
-  }
-  /**
-   * Deletes a specific instance configuration.
-   */
-  deleteInstance(instanceId) {
-    const all = this.load();
-    delete all[instanceId];
+    all[instanceId] = { ...all[instanceId] || {}, ...config, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
     this.save(all);
   }
   getUsageFilePath() {
     return this.usagePath;
   }
   exists(filePath) {
-    return fs && fs.existsSync(filePath);
+    return !!(fs && fs.existsSync(filePath));
   }
   loadUsage() {
     if (!fs || !this.usagePath || !fs.existsSync(this.usagePath)) return [];
     try {
-      const raw = fs.readFileSync(this.usagePath, "utf8");
-      return JSON.parse(raw);
+      return JSON.parse(fs.readFileSync(this.usagePath, "utf8"));
     } catch (e) {
       return [];
     }
@@ -183,15 +156,12 @@ var Registry = class _Registry {
     try {
       fs.writeFileSync(this.usagePath, JSON.stringify(data, null, 2), "utf8");
     } catch (e) {
-      console.error("[IK_REGISTRY] Failed to save usage:", e);
     }
   }
   clearUsage() {
     if (!fs || !this.usagePath) return;
     try {
-      if (fs.existsSync(this.usagePath)) {
-        fs.unlinkSync(this.usagePath);
-      }
+      if (fs.existsSync(this.usagePath)) fs.unlinkSync(this.usagePath);
     } catch (e) {
     }
   }
@@ -236,6 +206,9 @@ var ConfigManager = class {
     this.config = initialConfig;
     this.hooks = hooks;
     this.registry = Registry.getInstance();
+    if (hooks) {
+      this.registry.setHooks(hooks);
+    }
     this.loadFromRegistry();
   }
   getRegistry() {
@@ -243,6 +216,22 @@ var ConfigManager = class {
   }
   setHooks(hooks) {
     this.hooks = hooks;
+    this.registry.setHooks(hooks);
+  }
+  async hydrateFromHooks() {
+    if (this.hooks?.loadState) {
+      try {
+        const state = await this.hooks.loadState("ik_registry");
+        if (state) {
+          const parsed = JSON.parse(state);
+          const registry = this.registry;
+          registry.save(parsed);
+          this.loadFromRegistry();
+        }
+      } catch (e) {
+        console.warn("[IK_CONFIG] Hydration from hooks failed:", e);
+      }
+    }
   }
   loadFromRegistry() {
     const instanceConfigs = this.registry.load();
@@ -268,19 +257,16 @@ var ConfigManager = class {
     try {
       const baseUrl = this.config.centralReportEndpoint || "https://ik-firewall.vercel.app";
       const endpoint = `${baseUrl.replace(/\/$/, "")}/api/v1/sync`;
-      const instanceConfig2 = this.config.instanceConfigs?.[instanceId];
-      const registrationEmail = instanceConfig2?.ownerEmail || this.config.ownerEmail;
-      if ((!instanceConfig2?.licenseKey || instanceConfig2.licenseKey.startsWith("TRIAL-")) && registrationEmail) {
+      const registrationEmail = instanceConfig?.ownerEmail || this.config.ownerEmail;
+      if ((!instanceConfig?.licenseKey || instanceConfig.licenseKey.startsWith("TRIAL-")) && registrationEmail) {
         const success = await this.registerInstance(instanceId, registrationEmail);
         if (success) {
           this.hooks?.onStatus?.("\u2728 IK_SYNC: Zero-Config registration successful. License issued.");
           return;
-        } else {
-          this.hooks?.onStatus?.("\u26A0\uFE0F IK_SYNC: Auto-registration failed. Continuing with local trial.");
         }
       }
       this.hooks?.onStatus?.(`\u{1F4E1} IK_SYNC: Heartbeat to ${endpoint}...`);
-      const response = await fetch(`${endpoint}?licenseKey=${instanceConfig2?.licenseKey || ""}&instanceId=${instanceId}&version=2.2.0`);
+      const response = await fetch(`${endpoint}?licenseKey=${instanceConfig?.licenseKey || ""}&instanceId=${instanceId}&version=2.3.0`);
       if (response.ok) {
         const data = await response.json();
         if (this.config.hmacSecret) {
@@ -300,9 +286,6 @@ var ConfigManager = class {
       } else {
         throw new Error(`Server responded with ${response.status}`);
       }
-      if (!instanceConfig2?.firstUseDate) {
-        this.setInstanceConfig(instanceId, { firstUseDate: now.toISOString() });
-      }
     } catch (error) {
       console.error(`[IK_CONFIG] Remote sync failed (${error.message}). Falling open (Fail-Open mode).`);
       this.setInstanceConfig(instanceId, {
@@ -310,17 +293,6 @@ var ConfigManager = class {
         lastSyncDate: now.toISOString()
       });
     }
-    try {
-      const registry = this.registry;
-      if (registry.exists(registry.getUsageFilePath())) {
-        const aggregatedUsage = registry.loadUsage();
-        if (aggregatedUsage.length > 0) {
-          this.hooks?.onStatus?.(`\u{1F4CA} IK_SYNC: Found ${aggregatedUsage.length} pending usage reports. Preparation for Daily Flush...`);
-          this._pendingUsage = aggregatedUsage;
-        }
-      }
-    } catch (e) {
-    }
   }
   getConfig() {
     return { ...this.config };
@@ -1478,9 +1450,13 @@ var Orchestrator = class {
 
 // src/UsageTracker.ts
 var UsageTracker = class {
-  buffer = [];
-  MAX_BUFFER_SIZE = 1;
-  // Immediate reporting for Edge/Stateless environments
+  aggregationMap = /* @__PURE__ */ new Map();
+  retryQueue = [];
+  lastFlushTime = Date.now();
+  flushInProgress = false;
+  BATCH_SIZE_THRESHOLD = 50;
+  TIME_THRESHOLD_MS = 2e3;
+  MAX_RETRIES = 5;
   hooks;
   config;
   constructor(config, hooks) {
@@ -1488,113 +1464,116 @@ var UsageTracker = class {
     this.hooks = hooks;
   }
   /**
-   * Record a single AI interaction
+   * Record a single AI interaction and aggregate in memory
    */
   async logInteraction(params) {
-    const { instanceId, model, inputTokens, outputTokens, optimizedTokens = 0, cqScore, routingPath, clientOrigin, trace } = params;
+    const { instanceId, model, inputTokens, outputTokens, optimizedTokens = 0 } = params;
     const tokensSaved = optimizedTokens > 0 ? inputTokens - optimizedTokens : 0;
-    const instanceConfig = this.config.getConfig().instanceConfigs?.[instanceId];
-    const remotePricing = instanceConfig?.pricing?.[model] || { input: 5e-3, output: 0.015 };
-    const costSaved = tokensSaved / 1e3 * remotePricing.input;
-    const commissionDue = costSaved * 0.2;
-    const data = {
+    const totalTokens = inputTokens + outputTokens;
+    const day = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const aggKey = `${instanceId}:${model}:${day}`;
+    const existing = this.aggregationMap.get(aggKey) || {
+      modelName: model,
+      date: day,
+      tokensIn: 0,
+      tokensOut: 0,
+      tokensSaved: 0
+    };
+    existing.tokensIn += inputTokens;
+    existing.tokensOut += outputTokens;
+    existing.tokensSaved += tokensSaved;
+    this.aggregationMap.set(aggKey, existing);
+    this.hooks?.onUsage?.({
       instanceId,
       model_used: model,
-      routingPath,
+      routingPath: params.routingPath,
       input_tokens: inputTokens,
       output_tokens: outputTokens,
       optimized_tokens: optimizedTokens,
       tokens_saved: tokensSaved,
-      cost_saved: Number(costSaved.toFixed(6)),
-      commission_due: Number(commissionDue.toFixed(6)),
+      cost_saved: 0,
+      commission_due: 0,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       is_local: model === "local",
-      cq_score: cqScore,
-      clientOrigin,
-      trace
-    };
-    this.buffer.push(data);
-    this.hooks?.onUsageReported?.(data);
-    await this.persistToLocalBuffer(data);
+      cq_score: params.cqScore,
+      clientOrigin: params.clientOrigin,
+      trace: params.trace
+    });
+    this.hooks?.onUsageAggregate?.(existing);
+    await this.checkFlushConditions(instanceId);
+  }
+  async checkFlushConditions(instanceId) {
+    const now = Date.now();
+    const timeSinceFlush = now - this.lastFlushTime;
+    if (this.aggregationMap.size >= this.BATCH_SIZE_THRESHOLD || timeSinceFlush >= this.TIME_THRESHOLD_MS) {
+      this.performAsyncFlush(instanceId).catch((err) => {
+        console.error("[IK_TRACKER] Background flush failed:", err);
+      });
+    }
   }
-  /**
-   * Appends usage data to the local .ik-adapter/usage.json file
-   */
-  async persistToLocalBuffer(data) {
+  async performAsyncFlush(instanceId) {
+    if (this.flushInProgress || this.aggregationMap.size === 0) return;
+    this.flushInProgress = true;
+    const reports = Array.from(this.aggregationMap.values());
+    this.aggregationMap.clear();
+    this.lastFlushTime = Date.now();
+    const licenseKey = this.config.getConfig().instanceConfigs?.[instanceId]?.licenseKey || this.config.get("licenseKey");
+    const payload = {
+      licenseKey: licenseKey || "TRIAL-KEY",
+      instanceId,
+      timestamp: Date.now(),
+      reports
+    };
     try {
-      const registry = this.config.getRegistry();
-      const usageFile = registry.getUsageFilePath();
-      let existingUsage = [];
-      if (registry.exists(usageFile)) {
-        existingUsage = registry.loadUsage();
-      }
-      existingUsage.push(data);
-      registry.saveUsage(existingUsage);
-    } catch (e) {
-      console.error("[IK_TRACKER] Failed to persist usage to local buffer:", e);
+      await this.sendBatch(payload);
+    } catch (error) {
+      console.error("[IK_TRACKER] Batch send failed, queuing for retry:", error);
+      this.handleFailure(payload);
+    } finally {
+      this.flushInProgress = false;
     }
   }
-  /**
-   * Send buffered usage data to the central IK billing service
-   */
-  async flush(aggregatedData) {
-    const usageToFlush = aggregatedData || this.buffer;
-    if (usageToFlush.length === 0) return;
+  async sendBatch(payload) {
     const baseUrl = this.config.get("centralReportEndpoint") || "https://ik-firewall.vercel.app";
     const endpoint = `${baseUrl.replace(/\/$/, "")}/api/v1/report`;
-    const hmacSecret = this.config.get("hmacSecret");
-    try {
-      this.hooks?.onStatus?.(`\u{1F4E4} IK_TRACKER: Flushing ${usageToFlush.length} interactions to ${endpoint}...`);
-      const reportsByInstance = {};
-      for (const report of usageToFlush) {
-        if (!reportsByInstance[report.instanceId]) reportsByInstance[report.instanceId] = [];
-        reportsByInstance[report.instanceId].push(report);
-      }
-      for (const [instanceId, reports] of Object.entries(reportsByInstance)) {
-        const instanceConfig = this.config.getConfig().instanceConfigs?.[instanceId];
-        const payload = {
-          licenseKey: instanceConfig?.licenseKey || "",
-          instanceId,
-          reports: reports.map((r) => ({
-            modelName: r.model_used,
-            tokensIn: r.input_tokens,
-            tokensOut: r.output_tokens,
-            tokensSaved: r.tokens_saved,
-            date: r.timestamp
-          }))
-        };
-        if (hmacSecret) {
-          const jsonStr = JSON.stringify(payload);
-          try {
-            const crypto = typeof window === "undefined" ? (await import(
-              /* webpackIgnore: true */
-              "crypto"
-            )).default : null;
-            if (crypto && crypto.createHmac) {
-              payload.signature = crypto.createHmac("sha256", hmacSecret).update(jsonStr).digest("hex");
-            }
-          } catch (e) {
-          }
-        }
-        const response = await fetch(endpoint, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(payload)
-        });
-        if (!response.ok) {
-          console.error(`[IK_TRACKER] Failed to send aggregate for ${instanceId}: ${response.statusText}`);
+    const hmacSecret = this.config.get("hmacSecret") || process.env.IK_FIREWALL_SECRET;
+    if (hmacSecret) {
+      try {
+        const crypto = typeof window === "undefined" ? (await import("crypto")).default : null;
+        if (crypto && crypto.createHmac) {
+          payload.signature = crypto.createHmac("sha256", hmacSecret).update(JSON.stringify(payload)).digest("hex");
         }
+      } catch (e) {
       }
-      this.buffer = [];
-      if (aggregatedData) {
-        this.config.getRegistry().clearUsage();
+    }
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-ik-signature": payload.signature || ""
+      },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+    }
+    this.hooks?.onFlushSuccess?.(payload);
+  }
+  async handleFailure(payload) {
+    this.retryQueue.push(payload);
+    if (this.config.getRegistry() && typeof window === "undefined") {
+      try {
+        const registry = this.config.getRegistry();
+        const retryFile = registry.getUsageFilePath().replace("usage.json", "usage.retry.jsonl");
+      } catch (e) {
       }
-    } catch (error) {
-      console.error("[IK_TRACKER] Failed to flush usage data:", error);
+    }
+    if (this.hooks?.persistState) {
+      await this.hooks.persistState(`ik_retry_${payload.timestamp}`, JSON.stringify(payload));
     }
   }
   getBuffer() {
-    return [...this.buffer];
+    return Array.from(this.aggregationMap.values());
   }
 };
 
@@ -1869,20 +1848,20 @@ var IKFirewallCore = class _IKFirewallCore {
   async logConsumption(params) {
     return this.usageTracker.logInteraction(params);
   }
+  hydrated = false;
   /**
    * Primary Analysis Entry Point
    */
   async analyze(input, provider, personaName = "professional", locale, instanceId) {
+    if (!this.hydrated) {
+      await this.configManager.hydrateFromHooks();
+      this.hydrated = true;
+    }
     if (instanceId) {
       this.configManager.ensureInstanceConfig(instanceId);
-      const syncPromise = this.configManager.syncRemoteConfig(instanceId).then(async () => {
-        const pendingUsage = this.configManager._pendingUsage;
-        if (pendingUsage && pendingUsage.length > 0) {
-          await this.usageTracker.flush(pendingUsage);
-          this.configManager._pendingUsage = null;
-        }
+      this.configManager.syncRemoteConfig(instanceId).catch((err) => {
+        console.warn("[IK_CORE] Heartbeat sync failed:", err);
       });
-      await syncPromise;
     }
     const mergedConfig = this.configManager.getMergedConfig(instanceId);
     if (instanceId && mergedConfig?.isVerified === false) {

package/dist/index.d.cts

@@ -165,12 +165,31 @@ interface UsageData {
     clientOrigin?: string;
     trace?: any;
 }
+interface UsageAggregate {
+    modelName: string;
+    date: string;
+    tokensIn: number;
+    tokensOut: number;
+    tokensSaved: number;
+}
+interface BatchPayload {
+    licenseKey: string;
+    instanceId: string;
+    timestamp: number;
+    reports: UsageAggregate[];
+    signature?: string;
+}
 interface IKHooks {
     onDNAChange?: (dna: number) => void;
     onAuditComplete?: (metrics: IKMetrics) => void;
     onStatus?: (message: string) => void;
-    onUsageReported?: (usage: UsageData) => void;
+    onLicenseIssued?: (license: string) => void;
+    onUsage?: (usage: UsageData) => void;
+    onUsageAggregate?: (aggregate: UsageAggregate) => void;
+    onFlushSuccess?: (payload: BatchPayload) => void;
     onAuthorityExceeded?: (metrics: IKMetrics, prompt: string) => void | Promise<void>;
+    persistState?: (key: string, value: string) => Promise<void> | void;
+    loadState?: (key: string) => Promise<string | null> | string | null;
 }
 
 declare abstract class BaseProvider {
@@ -356,6 +375,7 @@ declare class IKFirewallCore {
         clientOrigin?: string;
         trace?: any;
     }): Promise<void>;
+    private hydrated;
     /**
      * Primary Analysis Entry Point
      */
@@ -705,4 +725,4 @@ declare const IKBenchmarks: {
     BIG_TEST: TestPrompt[];
 };
 
-export { type AIProvider, type AIResponse, AnthropicProvider, BaseProvider, type ContextMode, DeepSeekProvider, Dictionaries, DictionaryRegex, GeminiProvider, HeuristicGatekeeper, IKBenchmarks, type IKConfig, IKFirewallCore, type IKHooks, type IKMetrics, type IKPluginInfo, LocalProvider, type ModelRole, OpenAIProvider, PerplexityProvider, type PromptLength, type PromptType, type ProviderMode, type RuntimeStrategy, type StressReport, type StressTestCase, StressTester, SurgicalTester, type TestCase, type TestPrompt, type TestResult, type UsageData };
+export { type AIProvider, type AIResponse, AnthropicProvider, BaseProvider, type BatchPayload, type ContextMode, DeepSeekProvider, Dictionaries, DictionaryRegex, GeminiProvider, HeuristicGatekeeper, IKBenchmarks, type IKConfig, IKFirewallCore, type IKHooks, type IKMetrics, type IKPluginInfo, LocalProvider, type ModelRole, OpenAIProvider, PerplexityProvider, type PromptLength, type PromptType, type ProviderMode, type RuntimeStrategy, type StressReport, type StressTestCase, StressTester, SurgicalTester, type TestCase, type TestPrompt, type TestResult, type UsageAggregate, type UsageData };

package/dist/index.d.ts

@@ -165,12 +165,31 @@ interface UsageData {
     clientOrigin?: string;
     trace?: any;
 }
+interface UsageAggregate {
+    modelName: string;
+    date: string;
+    tokensIn: number;
+    tokensOut: number;
+    tokensSaved: number;
+}
+interface BatchPayload {
+    licenseKey: string;
+    instanceId: string;
+    timestamp: number;
+    reports: UsageAggregate[];
+    signature?: string;
+}
 interface IKHooks {
     onDNAChange?: (dna: number) => void;
     onAuditComplete?: (metrics: IKMetrics) => void;
     onStatus?: (message: string) => void;
-    onUsageReported?: (usage: UsageData) => void;
+    onLicenseIssued?: (license: string) => void;
+    onUsage?: (usage: UsageData) => void;
+    onUsageAggregate?: (aggregate: UsageAggregate) => void;
+    onFlushSuccess?: (payload: BatchPayload) => void;
     onAuthorityExceeded?: (metrics: IKMetrics, prompt: string) => void | Promise<void>;
+    persistState?: (key: string, value: string) => Promise<void> | void;
+    loadState?: (key: string) => Promise<string | null> | string | null;
 }
 
 declare abstract class BaseProvider {
@@ -356,6 +375,7 @@ declare class IKFirewallCore {
         clientOrigin?: string;
         trace?: any;
     }): Promise<void>;
+    private hydrated;
     /**
      * Primary Analysis Entry Point
      */
@@ -705,4 +725,4 @@ declare const IKBenchmarks: {
     BIG_TEST: TestPrompt[];
 };
 
-export { type AIProvider, type AIResponse, AnthropicProvider, BaseProvider, type ContextMode, DeepSeekProvider, Dictionaries, DictionaryRegex, GeminiProvider, HeuristicGatekeeper, IKBenchmarks, type IKConfig, IKFirewallCore, type IKHooks, type IKMetrics, type IKPluginInfo, LocalProvider, type ModelRole, OpenAIProvider, PerplexityProvider, type PromptLength, type PromptType, type ProviderMode, type RuntimeStrategy, type StressReport, type StressTestCase, StressTester, SurgicalTester, type TestCase, type TestPrompt, type TestResult, type UsageData };
+export { type AIProvider, type AIResponse, AnthropicProvider, BaseProvider, type BatchPayload, type ContextMode, DeepSeekProvider, Dictionaries, DictionaryRegex, GeminiProvider, HeuristicGatekeeper, IKBenchmarks, type IKConfig, IKFirewallCore, type IKHooks, type IKMetrics, type IKPluginInfo, LocalProvider, type ModelRole, OpenAIProvider, PerplexityProvider, type PromptLength, type PromptType, type ProviderMode, type RuntimeStrategy, type StressReport, type StressTestCase, StressTester, SurgicalTester, type TestCase, type TestPrompt, type TestResult, type UsageAggregate, type UsageData };

package/dist/index.js

@@ -8,17 +8,12 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 // src/Registry.ts
 var fs = null;
 var path = null;
-if (typeof window === "undefined") {
-  try {
-  } catch (e) {
-  }
-}
 var Registry = class _Registry {
   static instance;
   registryPath;
   usagePath;
+  hooks;
   hasWarnedNoFs = false;
-  hasWarnedSaveError = false;
   constructor() {
     this.registryPath = "";
     this.usagePath = "";
@@ -30,12 +25,6 @@ var Registry = class _Registry {
         this.usagePath = path.join(process.cwd(), ".ik-adapter", "usage.json");
         this.ensureDirectory();
       } catch (e) {
-        if (!this.hasWarnedNoFs) {
-          console.warn("\n[IK_REGISTRY] \u26A0\uFE0F WARNING: Node.js environment detected but fs/path modules failed to load. Falling back to in-memory mode.");
-          console.warn("[IK_REGISTRY] \u{1F4DD} INTEGRATOR NOTICE: Custom configurations (metaprompts, instances) will be LOST upon server restart or lambda spin-down.");
-          console.warn("[IK_REGISTRY] \u{1F4A1} BEST PRACTICE: Host on a traditional VPS (Node/Docker) or migrate settings to your database if you need persistence on Serverless runtimes.\n");
-          this.hasWarnedNoFs = true;
-        }
       }
     }
   }
@@ -45,23 +34,31 @@ var Registry = class _Registry {
     }
     return _Registry.instance;
   }
+  setHooks(hooks) {
+    this.hooks = hooks;
+  }
   ensureDirectory() {
     if (!fs || !path || !this.registryPath) return;
     try {
       const dir = path.dirname(this.registryPath);
-      if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-      }
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
     } catch (e) {
     }
   }
   /**
-   * Loads all instance configurations from the local registry file.
+   * Loads instance configurations with Hook support
    */
   load() {
-    if (!fs || !this.registryPath) return {};
-    try {
-      if (fs.existsSync(this.registryPath)) {
+    if (this.hooks?.loadState) {
+      try {
+        const hookData = this.hooks.loadState("ik_registry");
+        if (hookData) return JSON.parse(hookData);
+      } catch (e) {
+        console.warn("[IK_REGISTRY] Registry load via hook failed, falling back...");
+      }
+    }
+    if (fs && this.registryPath && fs.existsSync(this.registryPath)) {
+      try {
         const rawData = fs.readFileSync(this.registryPath, "utf8");
         try {
           const decoded = Buffer.from(rawData, "base64").toString("utf8");
@@ -69,69 +66,45 @@ var Registry = class _Registry {
         } catch (e) {
           return JSON.parse(rawData);
         }
+      } catch (error) {
+        console.error("[IK_REGISTRY] Local load error:", error);
       }
-    } catch (error) {
-      console.error("[IK_REGISTRY] Load error:", error);
     }
     return {};
   }
   save(data) {
-    if (!fs || !this.registryPath) {
-      if (!this.hasWarnedNoFs) {
-        console.warn("\n[IK_REGISTRY] \u26A0\uFE0F WARNING: No File System (fs) detected. Running in in-memory mode.");
-        console.warn("[IK_REGISTRY] \u{1F4DD} INTEGRATOR NOTICE: Custom configurations (metaprompts, instances) will be LOST upon server restart or lambda spin-down.");
-        console.warn("[IK_REGISTRY] \u{1F4A1} BEST PRACTICE: If hosting on Vercel/Serverless or Edge runtimes, do not rely on local JSON for dynamic config changes.");
-        console.warn("[IK_REGISTRY] \u{1F449} Consider migrating user-generated adapter settings to your database or host on a traditional VPS (Node/Docker) to ensure persistence.\n");
-        this.hasWarnedNoFs = true;
-      }
-      return;
+    const jsonStr = JSON.stringify(data, null, 2);
+    if (this.hooks?.persistState) {
+      this.hooks.persistState("ik_registry", jsonStr);
     }
-    try {
-      this.ensureDirectory();
-      const jsonStr = JSON.stringify(data, null, 2);
-      const obfuscated = Buffer.from(jsonStr).toString("base64");
-      fs.writeFileSync(this.registryPath, obfuscated, "utf8");
-    } catch (error) {
-      if (!this.hasWarnedSaveError) {
-        console.error("\n[IK_REGISTRY] \u{1F6A8} ERROR saving registry.json. Your environment likely has a read-only filesystem (e.g. Vercel Serverless).");
-        console.error("[IK_REGISTRY] \u{1F4DD} INTEGRATOR NOTICE: Serverless environments wipe or restrict file writes!");
-        console.error("[IK_REGISTRY] \u{1F4A1} BEST PRACTICE: Host on a traditional VPS (Node/Docker) or intercept state changes via Events/Database to ensure persistence.");
-        console.error("[IK_REGISTRY] Actual Error:", error.message, "\n");
-        this.hasWarnedSaveError = true;
+    if (fs && this.registryPath) {
+      try {
+        this.ensureDirectory();
+        const obfuscated = Buffer.from(jsonStr).toString("base64");
+        fs.writeFileSync(this.registryPath, obfuscated, "utf8");
+      } catch (error) {
+        if (!this.hasWarnedNoFs) {
+          console.warn("[IK_REGISTRY] Local write failed (likely Read-Only FS). Relying on hooks/memory.");
+          this.hasWarnedNoFs = true;
+        }
       }
     }
   }
-  /**
-   * Updates a specific instance configuration.
-   */
   updateInstance(instanceId, config) {
     const all = this.load();
-    all[instanceId] = {
-      ...all[instanceId] || {},
-      ...config,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    this.save(all);
-  }
-  /**
-   * Deletes a specific instance configuration.
-   */
-  deleteInstance(instanceId) {
-    const all = this.load();
-    delete all[instanceId];
+    all[instanceId] = { ...all[instanceId] || {}, ...config, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
     this.save(all);
   }
   getUsageFilePath() {
     return this.usagePath;
   }
   exists(filePath) {
-    return fs && fs.existsSync(filePath);
+    return !!(fs && fs.existsSync(filePath));
   }
   loadUsage() {
     if (!fs || !this.usagePath || !fs.existsSync(this.usagePath)) return [];
     try {
-      const raw = fs.readFileSync(this.usagePath, "utf8");
-      return JSON.parse(raw);
+      return JSON.parse(fs.readFileSync(this.usagePath, "utf8"));
     } catch (e) {
       return [];
     }
@@ -141,15 +114,12 @@ var Registry = class _Registry {
     try {
       fs.writeFileSync(this.usagePath, JSON.stringify(data, null, 2), "utf8");
     } catch (e) {
-      console.error("[IK_REGISTRY] Failed to save usage:", e);
     }
   }
   clearUsage() {
     if (!fs || !this.usagePath) return;
     try {
-      if (fs.existsSync(this.usagePath)) {
-        fs.unlinkSync(this.usagePath);
-      }
+      if (fs.existsSync(this.usagePath)) fs.unlinkSync(this.usagePath);
     } catch (e) {
     }
   }
@@ -194,6 +164,9 @@ var ConfigManager = class {
     this.config = initialConfig;
     this.hooks = hooks;
     this.registry = Registry.getInstance();
+    if (hooks) {
+      this.registry.setHooks(hooks);
+    }
     this.loadFromRegistry();
   }
   getRegistry() {
@@ -201,6 +174,22 @@ var ConfigManager = class {
   }
   setHooks(hooks) {
     this.hooks = hooks;
+    this.registry.setHooks(hooks);
+  }
+  async hydrateFromHooks() {
+    if (this.hooks?.loadState) {
+      try {
+        const state = await this.hooks.loadState("ik_registry");
+        if (state) {
+          const parsed = JSON.parse(state);
+          const registry = this.registry;
+          registry.save(parsed);
+          this.loadFromRegistry();
+        }
+      } catch (e) {
+        console.warn("[IK_CONFIG] Hydration from hooks failed:", e);
+      }
+    }
   }
   loadFromRegistry() {
     const instanceConfigs = this.registry.load();
@@ -226,19 +215,16 @@ var ConfigManager = class {
     try {
       const baseUrl = this.config.centralReportEndpoint || "https://ik-firewall.vercel.app";
       const endpoint = `${baseUrl.replace(/\/$/, "")}/api/v1/sync`;
-      const instanceConfig2 = this.config.instanceConfigs?.[instanceId];
-      const registrationEmail = instanceConfig2?.ownerEmail || this.config.ownerEmail;
-      if ((!instanceConfig2?.licenseKey || instanceConfig2.licenseKey.startsWith("TRIAL-")) && registrationEmail) {
+      const registrationEmail = instanceConfig?.ownerEmail || this.config.ownerEmail;
+      if ((!instanceConfig?.licenseKey || instanceConfig.licenseKey.startsWith("TRIAL-")) && registrationEmail) {
         const success = await this.registerInstance(instanceId, registrationEmail);
         if (success) {
           this.hooks?.onStatus?.("\u2728 IK_SYNC: Zero-Config registration successful. License issued.");
           return;
-        } else {
-          this.hooks?.onStatus?.("\u26A0\uFE0F IK_SYNC: Auto-registration failed. Continuing with local trial.");
         }
       }
       this.hooks?.onStatus?.(`\u{1F4E1} IK_SYNC: Heartbeat to ${endpoint}...`);
-      const response = await fetch(`${endpoint}?licenseKey=${instanceConfig2?.licenseKey || ""}&instanceId=${instanceId}&version=2.2.0`);
+      const response = await fetch(`${endpoint}?licenseKey=${instanceConfig?.licenseKey || ""}&instanceId=${instanceId}&version=2.3.0`);
       if (response.ok) {
         const data = await response.json();
         if (this.config.hmacSecret) {
@@ -258,9 +244,6 @@ var ConfigManager = class {
       } else {
         throw new Error(`Server responded with ${response.status}`);
       }
-      if (!instanceConfig2?.firstUseDate) {
-        this.setInstanceConfig(instanceId, { firstUseDate: now.toISOString() });
-      }
     } catch (error) {
       console.error(`[IK_CONFIG] Remote sync failed (${error.message}). Falling open (Fail-Open mode).`);
       this.setInstanceConfig(instanceId, {
@@ -268,17 +251,6 @@ var ConfigManager = class {
         lastSyncDate: now.toISOString()
       });
     }
-    try {
-      const registry = this.registry;
-      if (registry.exists(registry.getUsageFilePath())) {
-        const aggregatedUsage = registry.loadUsage();
-        if (aggregatedUsage.length > 0) {
-          this.hooks?.onStatus?.(`\u{1F4CA} IK_SYNC: Found ${aggregatedUsage.length} pending usage reports. Preparation for Daily Flush...`);
-          this._pendingUsage = aggregatedUsage;
-        }
-      }
-    } catch (e) {
-    }
   }
   getConfig() {
     return { ...this.config };
@@ -1436,9 +1408,13 @@ var Orchestrator = class {
 
 // src/UsageTracker.ts
 var UsageTracker = class {
-  buffer = [];
-  MAX_BUFFER_SIZE = 1;
-  // Immediate reporting for Edge/Stateless environments
+  aggregationMap = /* @__PURE__ */ new Map();
+  retryQueue = [];
+  lastFlushTime = Date.now();
+  flushInProgress = false;
+  BATCH_SIZE_THRESHOLD = 50;
+  TIME_THRESHOLD_MS = 2e3;
+  MAX_RETRIES = 5;
   hooks;
   config;
   constructor(config, hooks) {
@@ -1446,113 +1422,116 @@ var UsageTracker = class {
     this.hooks = hooks;
   }
   /**
-   * Record a single AI interaction
+   * Record a single AI interaction and aggregate in memory
    */
   async logInteraction(params) {
-    const { instanceId, model, inputTokens, outputTokens, optimizedTokens = 0, cqScore, routingPath, clientOrigin, trace } = params;
+    const { instanceId, model, inputTokens, outputTokens, optimizedTokens = 0 } = params;
     const tokensSaved = optimizedTokens > 0 ? inputTokens - optimizedTokens : 0;
-    const instanceConfig = this.config.getConfig().instanceConfigs?.[instanceId];
-    const remotePricing = instanceConfig?.pricing?.[model] || { input: 5e-3, output: 0.015 };
-    const costSaved = tokensSaved / 1e3 * remotePricing.input;
-    const commissionDue = costSaved * 0.2;
-    const data = {
+    const totalTokens = inputTokens + outputTokens;
+    const day = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const aggKey = `${instanceId}:${model}:${day}`;
+    const existing = this.aggregationMap.get(aggKey) || {
+      modelName: model,
+      date: day,
+      tokensIn: 0,
+      tokensOut: 0,
+      tokensSaved: 0
+    };
+    existing.tokensIn += inputTokens;
+    existing.tokensOut += outputTokens;
+    existing.tokensSaved += tokensSaved;
+    this.aggregationMap.set(aggKey, existing);
+    this.hooks?.onUsage?.({
       instanceId,
       model_used: model,
-      routingPath,
+      routingPath: params.routingPath,
       input_tokens: inputTokens,
       output_tokens: outputTokens,
       optimized_tokens: optimizedTokens,
       tokens_saved: tokensSaved,
-      cost_saved: Number(costSaved.toFixed(6)),
-      commission_due: Number(commissionDue.toFixed(6)),
+      cost_saved: 0,
+      commission_due: 0,
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       is_local: model === "local",
-      cq_score: cqScore,
-      clientOrigin,
-      trace
-    };
-    this.buffer.push(data);
-    this.hooks?.onUsageReported?.(data);
-    await this.persistToLocalBuffer(data);
+      cq_score: params.cqScore,
+      clientOrigin: params.clientOrigin,
+      trace: params.trace
+    });
+    this.hooks?.onUsageAggregate?.(existing);
+    await this.checkFlushConditions(instanceId);
+  }
+  async checkFlushConditions(instanceId) {
+    const now = Date.now();
+    const timeSinceFlush = now - this.lastFlushTime;
+    if (this.aggregationMap.size >= this.BATCH_SIZE_THRESHOLD || timeSinceFlush >= this.TIME_THRESHOLD_MS) {
+      this.performAsyncFlush(instanceId).catch((err) => {
+        console.error("[IK_TRACKER] Background flush failed:", err);
+      });
+    }
   }
-  /**
-   * Appends usage data to the local .ik-adapter/usage.json file
-   */
-  async persistToLocalBuffer(data) {
+  async performAsyncFlush(instanceId) {
+    if (this.flushInProgress || this.aggregationMap.size === 0) return;
+    this.flushInProgress = true;
+    const reports = Array.from(this.aggregationMap.values());
+    this.aggregationMap.clear();
+    this.lastFlushTime = Date.now();
+    const licenseKey = this.config.getConfig().instanceConfigs?.[instanceId]?.licenseKey || this.config.get("licenseKey");
+    const payload = {
+      licenseKey: licenseKey || "TRIAL-KEY",
+      instanceId,
+      timestamp: Date.now(),
+      reports
+    };
     try {
-      const registry = this.config.getRegistry();
-      const usageFile = registry.getUsageFilePath();
-      let existingUsage = [];
-      if (registry.exists(usageFile)) {
-        existingUsage = registry.loadUsage();
-      }
-      existingUsage.push(data);
-      registry.saveUsage(existingUsage);
-    } catch (e) {
-      console.error("[IK_TRACKER] Failed to persist usage to local buffer:", e);
+      await this.sendBatch(payload);
+    } catch (error) {
+      console.error("[IK_TRACKER] Batch send failed, queuing for retry:", error);
+      this.handleFailure(payload);
+    } finally {
+      this.flushInProgress = false;
     }
   }
-  /**
-   * Send buffered usage data to the central IK billing service
-   */
-  async flush(aggregatedData) {
-    const usageToFlush = aggregatedData || this.buffer;
-    if (usageToFlush.length === 0) return;
+  async sendBatch(payload) {
     const baseUrl = this.config.get("centralReportEndpoint") || "https://ik-firewall.vercel.app";
     const endpoint = `${baseUrl.replace(/\/$/, "")}/api/v1/report`;
-    const hmacSecret = this.config.get("hmacSecret");
-    try {
-      this.hooks?.onStatus?.(`\u{1F4E4} IK_TRACKER: Flushing ${usageToFlush.length} interactions to ${endpoint}...`);
-      const reportsByInstance = {};
-      for (const report of usageToFlush) {
-        if (!reportsByInstance[report.instanceId]) reportsByInstance[report.instanceId] = [];
-        reportsByInstance[report.instanceId].push(report);
-      }
-      for (const [instanceId, reports] of Object.entries(reportsByInstance)) {
-        const instanceConfig = this.config.getConfig().instanceConfigs?.[instanceId];
-        const payload = {
-          licenseKey: instanceConfig?.licenseKey || "",
-          instanceId,
-          reports: reports.map((r) => ({
-            modelName: r.model_used,
-            tokensIn: r.input_tokens,
-            tokensOut: r.output_tokens,
-            tokensSaved: r.tokens_saved,
-            date: r.timestamp
-          }))
-        };
-        if (hmacSecret) {
-          const jsonStr = JSON.stringify(payload);
-          try {
-            const crypto = typeof window === "undefined" ? (await import(
-              /* webpackIgnore: true */
-              "crypto"
-            )).default : null;
-            if (crypto && crypto.createHmac) {
-              payload.signature = crypto.createHmac("sha256", hmacSecret).update(jsonStr).digest("hex");
-            }
-          } catch (e) {
-          }
-        }
-        const response = await fetch(endpoint, {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(payload)
-        });
-        if (!response.ok) {
-          console.error(`[IK_TRACKER] Failed to send aggregate for ${instanceId}: ${response.statusText}`);
+    const hmacSecret = this.config.get("hmacSecret") || process.env.IK_FIREWALL_SECRET;
+    if (hmacSecret) {
+      try {
+        const crypto = typeof window === "undefined" ? (await import("crypto")).default : null;
+        if (crypto && crypto.createHmac) {
+          payload.signature = crypto.createHmac("sha256", hmacSecret).update(JSON.stringify(payload)).digest("hex");
         }
+      } catch (e) {
       }
-      this.buffer = [];
-      if (aggregatedData) {
-        this.config.getRegistry().clearUsage();
+    }
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-ik-signature": payload.signature || ""
+      },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+    }
+    this.hooks?.onFlushSuccess?.(payload);
+  }
+  async handleFailure(payload) {
+    this.retryQueue.push(payload);
+    if (this.config.getRegistry() && typeof window === "undefined") {
+      try {
+        const registry = this.config.getRegistry();
+        const retryFile = registry.getUsageFilePath().replace("usage.json", "usage.retry.jsonl");
+      } catch (e) {
       }
-    } catch (error) {
-      console.error("[IK_TRACKER] Failed to flush usage data:", error);
+    }
+    if (this.hooks?.persistState) {
+      await this.hooks.persistState(`ik_retry_${payload.timestamp}`, JSON.stringify(payload));
     }
   }
   getBuffer() {
-    return [...this.buffer];
+    return Array.from(this.aggregationMap.values());
   }
 };
 
@@ -1827,20 +1806,20 @@ var IKFirewallCore = class _IKFirewallCore {
   async logConsumption(params) {
     return this.usageTracker.logInteraction(params);
   }
+  hydrated = false;
   /**
    * Primary Analysis Entry Point
    */
   async analyze(input, provider, personaName = "professional", locale, instanceId) {
+    if (!this.hydrated) {
+      await this.configManager.hydrateFromHooks();
+      this.hydrated = true;
+    }
     if (instanceId) {
       this.configManager.ensureInstanceConfig(instanceId);
-      const syncPromise = this.configManager.syncRemoteConfig(instanceId).then(async () => {
-        const pendingUsage = this.configManager._pendingUsage;
-        if (pendingUsage && pendingUsage.length > 0) {
-          await this.usageTracker.flush(pendingUsage);
-          this.configManager._pendingUsage = null;
-        }
+      this.configManager.syncRemoteConfig(instanceId).catch((err) => {
+        console.warn("[IK_CORE] Heartbeat sync failed:", err);
       });
-      await syncPromise;
     }
     const mergedConfig = this.configManager.getMergedConfig(instanceId);
     if (instanceId && mergedConfig?.isVerified === false) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ik-firewall/core",
-  "version": "2.3.3",
+  "version": "2.3.4",
   "type": "module",
   "description": "The core IK Firewall engine for semantic-driven AI optimization.",
   "main": "./dist/index.js",