@liteguard/core 0.2.20260314 → 0.3.20260315

package/README.md

@@ -24,7 +24,7 @@ This is an **internal package** consumed by `@liteguard/liteguard-node`, `@liteg
 
 | Package | Description |
 |---|---|
-| [`@liteguard/liteguard`](https://www.npmjs.com/package/@liteguard/liteguard) | Umbrella package — automatic runtime resolution |
+| [`@liteguard/liteguard`](https://www.npmjs.com/package/@liteguard/liteguard) | Umbrella package. Automatic runtime resolution |
 | [`@liteguard/liteguard-node`](https://www.npmjs.com/package/@liteguard/liteguard-node) | Node.js runtime |
 | [`@liteguard/liteguard-browser`](https://www.npmjs.com/package/@liteguard/liteguard-browser) | Browser runtime |
 | [`@liteguard/liteguard-react`](https://www.npmjs.com/package/@liteguard/liteguard-react) | React bindings |
@@ -33,4 +33,4 @@ This is an **internal package** consumed by `@liteguard/liteguard-node`, `@liteg
 
 ## License
 
-Apache 2.0 — see [LICENSE](https://github.com/liteguard/liteguard/blob/main/LICENSE).
+Apache 2.0 see [LICENSE](https://github.com/liteguard/liteguard/blob/main/LICENSE).

package/dist/index.d.mts

@@ -39,7 +39,7 @@ interface ProtectedContext {
     signature: string;
 }
 interface GetGuardsRequest {
-    projectClientKeyId: string;
+    projectClientToken: string;
     environment: string;
     protectedContext?: ProtectedContext;
 }
@@ -91,10 +91,17 @@ interface Signal {
     droppedSignalsSinceLast: number;
     measurement?: SignalPerformance;
 }
+interface UnadoptedGuardObservation {
+    guardName: string;
+    firstSeenMs: number;
+    lastSeenMs: number;
+    checkCount: number;
+    estimatedChecksPerMinute: number;
+}
 interface SendUnadoptedGuardsRequest {
-    projectClientKeyId: string;
+    projectClientToken: string;
     environment: string;
-    guardNames: string[];
+    observations: UnadoptedGuardObservation[];
 }
 interface SendUnadoptedGuardsResponse {
     accepted: boolean;
@@ -225,7 +232,7 @@ interface RuntimeAdapter {
     clearInterval(handle: unknown): void;
     /**
      * Detach a timer handle so it does not prevent the process from exiting
-     * (e.g. call `handle.unref()` on Node.js). Optional — no-op by default.
+     * (e.g. call `handle.unref()` on Node.js). Optional, no-op by default.
      */
     detachTimer?(handle: unknown): void;
     /**
@@ -278,7 +285,7 @@ type ScopeSnapshot = {
 declare class LiteguardScope {
     private readonly client;
     private readonly snapshot;
-    /** @internal — use {@link BaseLiteguardClient.createScope} instead. */
+    /** @internal use {@link BaseLiteguardClient.createScope} instead. */
     constructor(client: BaseLiteguardClient, snapshot: ScopeSnapshot);
     /**
      * Derive a new scope with the given properties merged on top of this
@@ -289,7 +296,7 @@ declare class LiteguardScope {
      */
     withProperties(properties: Properties): LiteguardScope;
     /**
-     * Alias for {@link withProperties} — derives a new scope with additional properties.
+     * Alias for {@link withProperties} derives a new scope with additional properties.
      *
      * @param properties - Key/value pairs to add.
      * @returns A new {@link LiteguardScope} with the merged properties.
@@ -407,14 +414,13 @@ declare class LiteguardScope {
  * {@link RuntimeAdapter}.
  */
 declare class BaseLiteguardClient {
-    private readonly projectClientKeyId;
+    private readonly projectClientToken;
     private readonly runtime;
     private readonly options;
     private readonly bundles;
     private defaultScope;
     private signalBuffer;
     private droppedSignalsPending;
-    private readonly reportedUnadoptedGuards;
     private readonly pendingUnadoptedGuards;
     private refreshTimer;
     private flushTimer;
@@ -429,10 +435,10 @@ declare class BaseLiteguardClient {
      * and begin background timers.
      *
      * @param runtime - Platform adapter providing timers, fetch, and context storage.
-     * @param projectClientKeyId - Your project client key ID from the Liteguard dashboard.
+     * @param projectClientToken - Your project client token from the Liteguard dashboard.
      * @param options - Optional SDK configuration overrides.
      */
-    constructor(runtime: RuntimeAdapter, projectClientKeyId: string, options?: ClientOptions);
+    constructor(runtime: RuntimeAdapter, projectClientToken: string, options?: ClientOptions);
     /**
      * Fetch the initial public guard bundle and start background refresh and
      * flush timers. Must be called once after construction before using the
@@ -452,7 +458,7 @@ declare class BaseLiteguardClient {
      * Register a listener that is called whenever the guard bundle is refreshed.
      *
      * @param listener - Callback invoked on each guard bundle update.
-     * @returns An unsubscribe function — call it to remove the listener.
+     * @returns An unsubscribe function. Call it to remove the listener.
      *
      * @example
      * ```ts
@@ -629,8 +635,8 @@ declare class BaseLiteguardClient {
      */
     clearProtectedContext(): LiteguardScope;
     /**
-     * Immediately transmit all buffered telemetry signals to the backend. Also
-     * flushes any pending unadopted-guard reports.
+    * Immediately transmit all buffered telemetry signals to the backend. Also
+    * flushes any pending unadopted-guard observations.
      *
      * Call this before process exit or page unload to avoid losing signals.
      *
@@ -651,6 +657,8 @@ declare class BaseLiteguardClient {
     private resolveScope;
     /** Queue a one-time report for a guard that exists only in application code. */
     private recordUnadoptedGuard;
+    private mergePendingUnadoptedObservation;
+    private toUnadoptedGuardObservation;
     /** Schedule the next periodic guard refresh using the current refresh interval. */
     private scheduleNextRefresh;
     /** Refresh every cached bundle once, then reschedule the next cycle. */
@@ -705,8 +713,8 @@ declare class BaseLiteguardClient {
     _getRefreshRateSeconds(): number;
     /** @internal Return a cloned view of the buffered signals for tests and diagnostics. */
     _getSignalBuffer(): Signal[];
-    /** @internal Return the sorted set of queued unadopted guards. */
-    _getPendingUnadoptedGuards(): string[];
+    /** @internal Return the sorted set of queued unadopted guard observations. */
+    _getPendingUnadoptedGuards(): UnadoptedGuardObservation[];
     /** @internal Return the currently cached bundle keys. */
     _getBundleKeys(): string[];
     /** @internal Expose the request-scope store for tests. */
@@ -726,4 +734,4 @@ declare class BaseLiteguardClient {
  */
 declare function evaluateGuard(guard: Guard, properties: Properties): boolean;
 
-export { BaseLiteguardClient, type ClientOptions, type ExecutionAdapter, type ExecutionState, type FlushOptions, type GetGuardsRequest, type GetGuardsResponse, type Guard, type GuardCheckPerformance, type GuardExecutionPerformance, type LiteguardChangeListener, LiteguardScope, type MeasurementAdapter, type Operator, type Options, type Properties, type PropertyValue, type ProtectedContext, type RequestScopeAdapter, type RequestScopeStore, type Rule, type RuntimeAdapter, type ScopedOptions, type SendUnadoptedGuardsRequest, type SendUnadoptedGuardsResponse, type Signal, type SignalPerformance, type TraceContext, evaluateGuard };
+export { BaseLiteguardClient, type ClientOptions, type ExecutionAdapter, type ExecutionState, type FlushOptions, type GetGuardsRequest, type GetGuardsResponse, type Guard, type GuardCheckPerformance, type GuardExecutionPerformance, type LiteguardChangeListener, LiteguardScope, type MeasurementAdapter, type Operator, type Options, type Properties, type PropertyValue, type ProtectedContext, type RequestScopeAdapter, type RequestScopeStore, type Rule, type RuntimeAdapter, type ScopedOptions, type SendUnadoptedGuardsRequest, type SendUnadoptedGuardsResponse, type Signal, type SignalPerformance, type TraceContext, type UnadoptedGuardObservation, evaluateGuard };

package/dist/index.d.ts

@@ -39,7 +39,7 @@ interface ProtectedContext {
     signature: string;
 }
 interface GetGuardsRequest {
-    projectClientKeyId: string;
+    projectClientToken: string;
     environment: string;
     protectedContext?: ProtectedContext;
 }
@@ -91,10 +91,17 @@ interface Signal {
     droppedSignalsSinceLast: number;
     measurement?: SignalPerformance;
 }
+interface UnadoptedGuardObservation {
+    guardName: string;
+    firstSeenMs: number;
+    lastSeenMs: number;
+    checkCount: number;
+    estimatedChecksPerMinute: number;
+}
 interface SendUnadoptedGuardsRequest {
-    projectClientKeyId: string;
+    projectClientToken: string;
     environment: string;
-    guardNames: string[];
+    observations: UnadoptedGuardObservation[];
 }
 interface SendUnadoptedGuardsResponse {
     accepted: boolean;
@@ -225,7 +232,7 @@ interface RuntimeAdapter {
     clearInterval(handle: unknown): void;
     /**
      * Detach a timer handle so it does not prevent the process from exiting
-     * (e.g. call `handle.unref()` on Node.js). Optional — no-op by default.
+     * (e.g. call `handle.unref()` on Node.js). Optional, no-op by default.
      */
     detachTimer?(handle: unknown): void;
     /**
@@ -278,7 +285,7 @@ type ScopeSnapshot = {
 declare class LiteguardScope {
     private readonly client;
     private readonly snapshot;
-    /** @internal — use {@link BaseLiteguardClient.createScope} instead. */
+    /** @internal use {@link BaseLiteguardClient.createScope} instead. */
     constructor(client: BaseLiteguardClient, snapshot: ScopeSnapshot);
     /**
      * Derive a new scope with the given properties merged on top of this
@@ -289,7 +296,7 @@ declare class LiteguardScope {
      */
     withProperties(properties: Properties): LiteguardScope;
     /**
-     * Alias for {@link withProperties} — derives a new scope with additional properties.
+     * Alias for {@link withProperties} derives a new scope with additional properties.
      *
      * @param properties - Key/value pairs to add.
      * @returns A new {@link LiteguardScope} with the merged properties.
@@ -407,14 +414,13 @@ declare class LiteguardScope {
  * {@link RuntimeAdapter}.
  */
 declare class BaseLiteguardClient {
-    private readonly projectClientKeyId;
+    private readonly projectClientToken;
     private readonly runtime;
     private readonly options;
     private readonly bundles;
     private defaultScope;
     private signalBuffer;
     private droppedSignalsPending;
-    private readonly reportedUnadoptedGuards;
     private readonly pendingUnadoptedGuards;
     private refreshTimer;
     private flushTimer;
@@ -429,10 +435,10 @@ declare class BaseLiteguardClient {
      * and begin background timers.
      *
      * @param runtime - Platform adapter providing timers, fetch, and context storage.
-     * @param projectClientKeyId - Your project client key ID from the Liteguard dashboard.
+     * @param projectClientToken - Your project client token from the Liteguard dashboard.
      * @param options - Optional SDK configuration overrides.
      */
-    constructor(runtime: RuntimeAdapter, projectClientKeyId: string, options?: ClientOptions);
+    constructor(runtime: RuntimeAdapter, projectClientToken: string, options?: ClientOptions);
     /**
      * Fetch the initial public guard bundle and start background refresh and
      * flush timers. Must be called once after construction before using the
@@ -452,7 +458,7 @@ declare class BaseLiteguardClient {
      * Register a listener that is called whenever the guard bundle is refreshed.
      *
      * @param listener - Callback invoked on each guard bundle update.
-     * @returns An unsubscribe function — call it to remove the listener.
+     * @returns An unsubscribe function. Call it to remove the listener.
      *
      * @example
      * ```ts
@@ -629,8 +635,8 @@ declare class BaseLiteguardClient {
      */
     clearProtectedContext(): LiteguardScope;
     /**
-     * Immediately transmit all buffered telemetry signals to the backend. Also
-     * flushes any pending unadopted-guard reports.
+    * Immediately transmit all buffered telemetry signals to the backend. Also
+    * flushes any pending unadopted-guard observations.
      *
      * Call this before process exit or page unload to avoid losing signals.
      *
@@ -651,6 +657,8 @@ declare class BaseLiteguardClient {
     private resolveScope;
     /** Queue a one-time report for a guard that exists only in application code. */
     private recordUnadoptedGuard;
+    private mergePendingUnadoptedObservation;
+    private toUnadoptedGuardObservation;
     /** Schedule the next periodic guard refresh using the current refresh interval. */
     private scheduleNextRefresh;
     /** Refresh every cached bundle once, then reschedule the next cycle. */
@@ -705,8 +713,8 @@ declare class BaseLiteguardClient {
     _getRefreshRateSeconds(): number;
     /** @internal Return a cloned view of the buffered signals for tests and diagnostics. */
     _getSignalBuffer(): Signal[];
-    /** @internal Return the sorted set of queued unadopted guards. */
-    _getPendingUnadoptedGuards(): string[];
+    /** @internal Return the sorted set of queued unadopted guard observations. */
+    _getPendingUnadoptedGuards(): UnadoptedGuardObservation[];
     /** @internal Return the currently cached bundle keys. */
     _getBundleKeys(): string[];
     /** @internal Expose the request-scope store for tests. */
@@ -726,4 +734,4 @@ declare class BaseLiteguardClient {
  */
 declare function evaluateGuard(guard: Guard, properties: Properties): boolean;
 
-export { BaseLiteguardClient, type ClientOptions, type ExecutionAdapter, type ExecutionState, type FlushOptions, type GetGuardsRequest, type GetGuardsResponse, type Guard, type GuardCheckPerformance, type GuardExecutionPerformance, type LiteguardChangeListener, LiteguardScope, type MeasurementAdapter, type Operator, type Options, type Properties, type PropertyValue, type ProtectedContext, type RequestScopeAdapter, type RequestScopeStore, type Rule, type RuntimeAdapter, type ScopedOptions, type SendUnadoptedGuardsRequest, type SendUnadoptedGuardsResponse, type Signal, type SignalPerformance, type TraceContext, evaluateGuard };
+export { BaseLiteguardClient, type ClientOptions, type ExecutionAdapter, type ExecutionState, type FlushOptions, type GetGuardsRequest, type GetGuardsResponse, type Guard, type GuardCheckPerformance, type GuardExecutionPerformance, type LiteguardChangeListener, LiteguardScope, type MeasurementAdapter, type Operator, type Options, type Properties, type PropertyValue, type ProtectedContext, type RequestScopeAdapter, type RequestScopeStore, type Rule, type RuntimeAdapter, type ScopedOptions, type SendUnadoptedGuardsRequest, type SendUnadoptedGuardsResponse, type Signal, type SignalPerformance, type TraceContext, type UnadoptedGuardObservation, evaluateGuard };

package/dist/index.js

@@ -156,7 +156,7 @@ var signalCounter = 0;
 var LiteguardScope = class {
   client;
   snapshot;
-  /** @internal — use {@link BaseLiteguardClient.createScope} instead. */
+  /** @internal use {@link BaseLiteguardClient.createScope} instead. */
   constructor(client, snapshot) {
     this.client = client;
     this.snapshot = {
@@ -181,7 +181,7 @@ var LiteguardScope = class {
     });
   }
   /**
-   * Alias for {@link withProperties} — derives a new scope with additional properties.
+   * Alias for {@link withProperties} derives a new scope with additional properties.
    *
    * @param properties - Key/value pairs to add.
    * @returns A new {@link LiteguardScope} with the merged properties.
@@ -333,15 +333,14 @@ var LiteguardScope = class {
   }
 };
 var BaseLiteguardClient = class {
-  projectClientKeyId;
+  projectClientToken;
   runtime;
   options;
   bundles = /* @__PURE__ */ new Map();
   defaultScope;
   signalBuffer = [];
   droppedSignalsPending = 0;
-  reportedUnadoptedGuards = /* @__PURE__ */ new Set();
-  pendingUnadoptedGuards = /* @__PURE__ */ new Set();
+  pendingUnadoptedGuards = /* @__PURE__ */ new Map();
   refreshTimer = null;
   flushTimer = null;
   lifecycleCleanup = null;
@@ -355,12 +354,12 @@ var BaseLiteguardClient = class {
    * and begin background timers.
    *
    * @param runtime - Platform adapter providing timers, fetch, and context storage.
-   * @param projectClientKeyId - Your project client key ID from the Liteguard dashboard.
+   * @param projectClientToken - Your project client token from the Liteguard dashboard.
    * @param options - Optional SDK configuration overrides.
    */
-  constructor(runtime, projectClientKeyId, options = {}) {
+  constructor(runtime, projectClientToken, options = {}) {
     this.runtime = runtime;
-    this.projectClientKeyId = projectClientKeyId;
+    this.projectClientToken = projectClientToken;
     this.options = {
       environment: options.environment ?? "",
       fallback: options.fallback ?? false,
@@ -429,7 +428,7 @@ var BaseLiteguardClient = class {
    * Register a listener that is called whenever the guard bundle is refreshed.
    *
    * @param listener - Callback invoked on each guard bundle update.
-   * @returns An unsubscribe function — call it to remove the listener.
+   * @returns An unsubscribe function. Call it to remove the listener.
    *
    * @example
    * ```ts
@@ -879,8 +878,8 @@ var BaseLiteguardClient = class {
     return this.replaceCurrentScope(nextScope);
   }
   /**
-   * Immediately transmit all buffered telemetry signals to the backend. Also
-   * flushes any pending unadopted-guard reports.
+  * Immediately transmit all buffered telemetry signals to the backend. Also
+  * flushes any pending unadopted-guard observations.
    *
    * Call this before process exit or page unload to avoid losing signals.
    *
@@ -888,13 +887,13 @@ var BaseLiteguardClient = class {
    */
   async flushSignals(options = {}) {
     const signalBatch = this.signalBuffer.splice(0);
-    const unadoptedGuardNames = [...this.pendingUnadoptedGuards];
+    const unadoptedObservations = [...this.pendingUnadoptedGuards.values()].sort((a, b) => a.guardName.localeCompare(b.guardName)).map((observation) => this.toUnadoptedGuardObservation(observation));
     this.pendingUnadoptedGuards.clear();
     if (signalBatch.length > 0) {
       try {
         const url = new URL("/api/v1/signals", this.options.backendUrl);
         const body = JSON.stringify({
-          projectClientKeyId: this.projectClientKeyId,
+          projectClientToken: this.projectClientToken,
           environment: this.options.environment,
           signals: signalBatch
         });
@@ -909,19 +908,19 @@ var BaseLiteguardClient = class {
         }
       }
     }
-    if (unadoptedGuardNames.length > 0) {
+    if (unadoptedObservations.length > 0) {
       try {
         const url = new URL("/api/v1/unadopted-guards", this.options.backendUrl);
         const requestBody = {
-          projectClientKeyId: this.projectClientKeyId,
+          projectClientToken: this.projectClientToken,
           environment: this.options.environment,
-          guardNames: unadoptedGuardNames
+          observations: unadoptedObservations
         };
         await this.post(url, JSON.stringify(requestBody), options.keepalive);
       } catch (error) {
         this.log("[liteguard] Unadopted guard flush failed", error);
-        for (const guardName of unadoptedGuardNames) {
-          this.pendingUnadoptedGuards.add(guardName);
+        for (const observation of unadoptedObservations) {
+          this.mergePendingUnadoptedObservation(observation);
         }
       }
     }
@@ -987,10 +986,44 @@ var BaseLiteguardClient = class {
   }
   /** Queue a one-time report for a guard that exists only in application code. */
   recordUnadoptedGuard(name) {
-    if (!this.reportedUnadoptedGuards.has(name)) {
-      this.reportedUnadoptedGuards.add(name);
-      this.pendingUnadoptedGuards.add(name);
+    const now = Date.now();
+    const existing = this.pendingUnadoptedGuards.get(name);
+    if (existing) {
+      existing.lastSeenMs = now;
+      existing.checkCount += 1;
+      return;
     }
+    this.pendingUnadoptedGuards.set(name, {
+      guardName: name,
+      firstSeenMs: now,
+      lastSeenMs: now,
+      checkCount: 1
+    });
+  }
+  mergePendingUnadoptedObservation(observation) {
+    const existing = this.pendingUnadoptedGuards.get(observation.guardName);
+    if (!existing) {
+      this.pendingUnadoptedGuards.set(observation.guardName, {
+        guardName: observation.guardName,
+        firstSeenMs: observation.firstSeenMs,
+        lastSeenMs: observation.lastSeenMs,
+        checkCount: observation.checkCount
+      });
+      return;
+    }
+    existing.firstSeenMs = Math.min(existing.firstSeenMs, observation.firstSeenMs);
+    existing.lastSeenMs = Math.max(existing.lastSeenMs, observation.lastSeenMs);
+    existing.checkCount += observation.checkCount;
+  }
+  toUnadoptedGuardObservation(observation) {
+    return {
+      ...observation,
+      estimatedChecksPerMinute: estimateChecksPerMinute(
+        observation.firstSeenMs,
+        observation.lastSeenMs,
+        observation.checkCount
+      )
+    };
   }
   /** Schedule the next periodic guard refresh using the current refresh interval. */
   scheduleNextRefresh() {
@@ -1075,14 +1108,14 @@ var BaseLiteguardClient = class {
     try {
       const url = new URL("/api/v1/guards", this.options.backendUrl);
       const headers = {
-        Authorization: `Bearer ${this.projectClientKeyId}`,
+        Authorization: `Bearer ${this.projectClientToken}`,
         "Content-Type": "application/json"
       };
       if (etag) {
         headers["If-None-Match"] = etag;
       }
       const requestBody = {
-        projectClientKeyId: this.projectClientKeyId,
+        projectClientToken: this.projectClientToken,
         environment: this.options.environment,
         ...protectedContext ? { protectedContext } : {}
       };
@@ -1148,7 +1181,7 @@ var BaseLiteguardClient = class {
       const res = await this.runtime.fetch(url.toString(), {
         method: "POST",
         headers: {
-          Authorization: `Bearer ${this.projectClientKeyId}`,
+          Authorization: `Bearer ${this.projectClientToken}`,
           "Content-Type": "application/json",
           ...this.options.environment && { "X-Liteguard-Environment": this.options.environment }
         },
@@ -1346,9 +1379,9 @@ var BaseLiteguardClient = class {
       ...signal.properties ? { properties: { ...signal.properties } } : {}
     }));
   }
-  /** @internal Return the sorted set of queued unadopted guards. */
+  /** @internal Return the sorted set of queued unadopted guard observations. */
   _getPendingUnadoptedGuards() {
-    return [...this.pendingUnadoptedGuards].sort();
+    return [...this.pendingUnadoptedGuards.values()].sort((a, b) => a.guardName.localeCompare(b.guardName)).map((observation) => this.toUnadoptedGuardObservation(observation));
   }
   /** @internal Return the currently cached bundle keys. */
   _getBundleKeys() {
@@ -1363,6 +1396,13 @@ function nextSignalId() {
   signalCounter += 1;
   return `${Date.now().toString(36)}-${signalCounter.toString(36)}`;
 }
+function estimateChecksPerMinute(firstSeenMs, lastSeenMs, checkCount) {
+  if (checkCount <= 0) {
+    return 0;
+  }
+  const windowMs = Math.max(1e3, lastSeenMs - firstSeenMs);
+  return checkCount * 6e4 / windowMs;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseLiteguardClient,