@liteguard/core 0.2.20260314

package/dist/index.d.ts

@@ -0,0 +1,729 @@
+type PropertyValue = boolean | string | number;
+type Properties = Record<string, PropertyValue>;
+type Operator = 'EQUALS' | 'NOT_EQUALS' | 'IN' | 'NOT_IN' | 'REGEX' | 'GT' | 'GTE' | 'LT' | 'LTE';
+interface Rule {
+    propertyName: string;
+    operator: Operator;
+    values: PropertyValue[];
+    result: boolean;
+    enabled: boolean;
+}
+interface Guard {
+    name: string;
+    rules: Rule[];
+    defaultValue: boolean;
+    adopted: boolean;
+    rateLimitPerMinute: number;
+    rateLimitProperties: string[];
+    disableMeasurement?: boolean;
+}
+interface ClientOptions {
+    environment?: string;
+    fallback?: boolean;
+    refreshRateSeconds?: number;
+    flushRateSeconds?: number;
+    flushSize?: number;
+    backendUrl?: string;
+    quiet?: boolean;
+    httpTimeoutSeconds?: number;
+    flushBufferMultiplier?: number;
+    disableMeasurement?: boolean;
+}
+interface Options {
+    properties?: Record<string, PropertyValue>;
+    fallback?: boolean;
+    disableMeasurement?: boolean;
+}
+interface ProtectedContext {
+    properties?: Record<string, string>;
+    signature: string;
+}
+interface GetGuardsRequest {
+    projectClientKeyId: string;
+    environment: string;
+    protectedContext?: ProtectedContext;
+}
+interface GetGuardsResponse {
+    guards: Guard[];
+    refreshRateSeconds: number;
+    etag: string;
+}
+interface TraceContext {
+    traceId: string;
+    spanId: string;
+    parentSpanId: string;
+}
+interface GuardCheckPerformance {
+    rssBytes?: number;
+    heapUsedBytes?: number;
+    heapTotalBytes?: number;
+    cpuTimeNs?: number;
+    gcCount?: number;
+    threadCount?: number;
+}
+interface GuardExecutionPerformance {
+    durationNs: number;
+    rssEndBytes?: number;
+    heapUsedEndBytes?: number;
+    heapTotalEndBytes?: number;
+    cpuTimeEndNs?: number;
+    gcCountEnd?: number;
+    threadCountEnd?: number;
+    completed: boolean;
+    errorClass?: string;
+}
+interface SignalPerformance {
+    guardCheck?: GuardCheckPerformance;
+    guardExecution?: GuardExecutionPerformance;
+}
+interface Signal {
+    guardName: string;
+    result: boolean;
+    properties?: Record<string, PropertyValue>;
+    timestampMs: number;
+    trace?: TraceContext;
+    signalId: string;
+    executionId: string;
+    parentSignalId?: string;
+    sequenceNumber: number;
+    callsiteId: string;
+    kind: string;
+    droppedSignalsSinceLast: number;
+    measurement?: SignalPerformance;
+}
+interface SendUnadoptedGuardsRequest {
+    projectClientKeyId: string;
+    environment: string;
+    guardNames: string[];
+}
+interface SendUnadoptedGuardsResponse {
+    accepted: boolean;
+}
+
+/**
+ * Snapshot of an in-flight execution scope, used to correlate guard check
+ * and guard execution signals within a single logical operation.
+ */
+type ExecutionState = {
+    /** Unique identifier shared by all signals in this execution. */
+    executionId: string;
+    /** Signal ID of the most recently emitted signal in this execution. */
+    lastSignalId?: string;
+    /** Monotonically increasing counter within the execution. */
+    sequenceNumber: number;
+};
+/**
+ * Holds the active {@link LiteguardScope} for the current request or
+ * async context (e.g. via `AsyncLocalStorage` on Node.js).
+ */
+type RequestScopeStore = {
+    currentScope: unknown;
+};
+/**
+ * Adapter that manages execution-scoped state so that guard signals emitted
+ * within the same logical operation share a common execution ID.
+ *
+ * Implementations should use a context-propagation mechanism appropriate for
+ * the runtime (e.g. `AsyncLocalStorage` on Node.js, stack-based on browsers).
+ */
+interface ExecutionAdapter {
+    /** Return the current execution state, or `undefined` if none is active. */
+    getStore(): ExecutionState | undefined;
+    /**
+     * Run `fn` within a new execution context initialised with `initialState`.
+     *
+     * @param initialState - Fresh execution state for the new context.
+     * @param fn - Callback to execute within the context.
+     * @returns The return value of `fn`.
+     */
+    run<T>(initialState: ExecutionState, fn: () => T): T;
+}
+/**
+ * Adapter that manages per-request scope propagation so that properties and
+ * protected context are automatically available to guard checks within the
+ * same request or async context.
+ */
+interface RequestScopeAdapter {
+    /** Return the current request-scope store, or `undefined` if none is active. */
+    getStore(): RequestScopeStore | undefined;
+    /**
+     * Run `fn` within the given request-scope store.
+     *
+     * @param initialState - The scope store to attach to the context.
+     * @param fn - Callback to execute within the scoped context.
+     * @returns The return value of `fn`.
+     */
+    run<T>(initialState: RequestScopeStore, fn: () => T): T;
+}
+/**
+ * Adapter that captures runtime performance metrics for guard check and
+ * guard execution signals.
+ *
+ * Implementations should return whatever metrics are cheaply available on the
+ * target platform (memory, CPU time, etc.). Returning `undefined` from a
+ * capture method disables measurement for that signal.
+ */
+interface MeasurementAdapter {
+    /**
+     * Begin measuring a guard execution. Returns an opaque start token that
+     * will be passed back to {@link captureGuardExecution}.
+     */
+    beginGuardExecution(): unknown;
+    /**
+     * Capture a snapshot of runtime metrics at the moment a guard is checked.
+     *
+     * @returns A measurement payload, or `undefined` to skip measurement.
+     */
+    captureGuardCheck(): NonNullable<Signal['measurement']> | undefined;
+    /**
+     * Capture a snapshot of runtime metrics at the end of a guard execution.
+     *
+     * @param startToken - The opaque token returned by {@link beginGuardExecution}.
+     * @param completed - Whether the guarded function completed without throwing.
+     * @param error - The thrown error, if any.
+     * @returns A measurement payload, or `undefined` to skip measurement.
+     */
+    captureGuardExecution(startToken: unknown, completed: boolean, error?: unknown): NonNullable<Signal['measurement']> | undefined;
+}
+/**
+ * Platform abstraction layer that allows the Liteguard core to run on
+ * Node.js, browsers, or other JavaScript runtimes without direct
+ * dependencies on platform-specific APIs.
+ *
+ * Provide an implementation of this interface to
+ * {@link BaseLiteguardClient} when constructing a client for a new runtime.
+ */
+interface RuntimeAdapter {
+    /** Human-readable runtime name (e.g. `"node"`, `"browser"`). */
+    readonly name: string;
+    /** Whether request/execution context remains correct across `await` boundaries. */
+    readonly supportsAsyncContextPropagation?: boolean;
+    /**
+     * Stack-frame substrings used to filter internal SDK frames when
+     * capturing call-site identifiers for telemetry signals.
+     */
+    readonly internalStackMarkers: string[];
+    /** Execution-scope adapter for signal correlation. */
+    readonly execution: ExecutionAdapter;
+    /** Optional request-scope adapter for per-request context propagation. */
+    readonly requestScope?: RequestScopeAdapter;
+    /** Performance measurement adapter. */
+    readonly measurement: MeasurementAdapter;
+    /** Return the current wall-clock time in milliseconds (like `Date.now()`). */
+    now(): number;
+    /** Return a monotonic timestamp in milliseconds (like `performance.now()`). */
+    monotonicNow(): number;
+    /** Perform an HTTP fetch with the given URL and options. */
+    fetch(input: string, init: RequestInit): Promise<Response>;
+    /** Schedule a one-shot timer. Returns an opaque handle for {@link clearTimeout}. */
+    setTimeout(callback: () => void, ms: number): unknown;
+    /** Cancel a timer created by {@link setTimeout}. */
+    clearTimeout(handle: unknown): void;
+    /** Schedule a repeating timer. Returns an opaque handle for {@link clearInterval}. */
+    setInterval(callback: () => void, ms: number): unknown;
+    /** Cancel a timer created by {@link setInterval}. */
+    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.
+     */
+    detachTimer?(handle: unknown): void;
+    /**
+     * Install platform lifecycle hooks (e.g. `visibilitychange` / `pagehide`
+     * in browsers) that flush buffered signals before the page unloads.
+     *
+     * @returns A cleanup function that removes the installed hooks, or `void`.
+     */
+    installLifecycleHooks?(hooks: {
+        flushKeepalive: () => void;
+    }): (() => void) | void;
+}
+
+/** Callback invoked whenever the guard bundle is refreshed from the backend. */
+type LiteguardChangeListener = () => void;
+/** Options for {@link BaseLiteguardClient.flushSignals}. */
+type FlushOptions = {
+    /**
+     * When `true`, the underlying `fetch` request is sent with the
+     * [`keepalive`](https://developer.mozilla.org/en-US/docs/Web/API/Request/keepalive)
+     * flag so it survives page navigation. Set this when flushing during
+     * `visibilitychange` or `pagehide` in the browser.
+     */
+    keepalive?: boolean;
+};
+/**
+ * Per-call options accepted by guard-evaluation methods. Extends the
+ * standard {@link Options} with an optional explicit {@link LiteguardScope}.
+ */
+type ScopedOptions = Partial<Options> & {
+    /**
+     * Explicit scope to evaluate against. When omitted the client resolves the
+     * scope from the current async context or falls back to the default scope.
+     */
+    scope?: LiteguardScope;
+};
+type ScopeSnapshot = {
+    properties: Properties;
+    protectedBundleKey: string;
+    protectedContext: ProtectedContext | null;
+};
+/**
+ * An immutable snapshot of evaluation context (properties and optional
+ * protected context) that can be passed to guard-evaluation methods.
+ *
+ * Scopes are created via {@link BaseLiteguardClient.createScope} or by
+ * deriving from an existing scope with methods like {@link withProperties}.
+ * They are cheap to create and safe to share across async boundaries.
+ */
+declare class LiteguardScope {
+    private readonly client;
+    private readonly snapshot;
+    /** @internal — use {@link BaseLiteguardClient.createScope} instead. */
+    constructor(client: BaseLiteguardClient, snapshot: ScopeSnapshot);
+    /**
+     * Derive a new scope with the given properties merged on top of this
+     * scope's existing properties. Does not mutate the current scope.
+     *
+     * @param properties - Key/value pairs to merge into the new scope.
+     * @returns A new {@link LiteguardScope} with the merged properties.
+     */
+    withProperties(properties: Properties): LiteguardScope;
+    /**
+     * 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.
+     */
+    addProperties(properties: Properties): LiteguardScope;
+    /**
+     * Derive a new scope with the specified property keys removed.
+     *
+     * @param names - Property keys to remove.
+     * @returns A new {@link LiteguardScope} without the listed properties.
+     */
+    clearProperties(names: string[]): LiteguardScope;
+    /**
+     * Derive a new scope with all properties removed.
+     *
+     * @returns A new {@link LiteguardScope} with an empty property bag.
+     */
+    resetProperties(): LiteguardScope;
+    /**
+     * Derive a new scope bound to the supplied protected context. The client
+     * will fetch (or reuse) a guard bundle specific to this context.
+     *
+     * @param protectedContext - Signed context bundle from your auth backend.
+     * @returns A new {@link LiteguardScope} bound to the protected context.
+     */
+    bindProtectedContext(protectedContext: ProtectedContext): Promise<LiteguardScope>;
+    /**
+     * Derive a new scope with protected context cleared, reverting to the
+     * public guard bundle.
+     *
+     * @returns A new {@link LiteguardScope} using the public guard bundle.
+     */
+    clearProtectedContext(): LiteguardScope;
+    /**
+     * Check whether the named guard is open within this scope. Buffers a
+     * `guard_check` telemetry signal.
+     *
+     * @param name - Guard name (e.g. `"payments.checkout"`).
+     * @param options - Optional per-call overrides (extra properties, fallback).
+     * @returns `true` if the guard is open, `false` otherwise.
+     */
+    isOpen(name: string, options?: Partial<Options>): boolean;
+    /**
+     * Check whether the named guard is open without emitting a telemetry
+     * signal or consuming a rate-limit slot. Useful in hot paths or render
+     * loops where you only need the boolean result.
+     *
+     * @param name - Guard name to evaluate.
+     * @param options - Optional per-call overrides.
+     * @returns `true` if the guard is open, `false` otherwise.
+     */
+    peekIsOpen(name: string, options?: Partial<Options>): boolean;
+    /**
+     * Evaluate the guard and, if open, call `fn` within a correlated execution
+     * scope. Returns `fn`'s result when open, or `undefined` when closed.
+     *
+     * Emits both a `guard_check` and a `guard_execution` telemetry signal so
+     * you can measure the guarded code path.
+     *
+     * @param name - Guard name to evaluate.
+     * @param fn - Synchronous function to invoke when the guard is open.
+     * @param options - Optional per-call overrides.
+     * @returns The return value of `fn`, or `undefined` if the guard is closed.
+     */
+    executeIfOpen<T>(name: string, fn: () => T, options?: Partial<Options>): T | undefined;
+    /**
+     * Async variant of {@link executeIfOpen}. Evaluates the guard and, if open,
+     * awaits `fn` within a correlated execution scope.
+     *
+     * @param name - Guard name to evaluate.
+     * @param fn - Async function to invoke when the guard is open.
+     * @param options - Optional per-call overrides.
+     * @returns The resolved value of `fn`, or `undefined` if the guard is closed.
+     */
+    executeIfOpenAsync<T>(name: string, fn: () => Promise<T>, options?: Partial<Options>): Promise<T | undefined>;
+    /**
+     * Run `fn` with this scope as the active scope for all guard checks made
+     * during its execution.
+     *
+     * @param fn - Callback to execute within this scope.
+     * @returns The return value of `fn`.
+     */
+    run<T>(fn: () => T): T;
+    /**
+     * Run `fn` with this scope active **and** inside a Liteguard execution
+     * context so that all guard signals share a common execution ID.
+     *
+     * @param fn - Callback to execute.
+     * @returns The return value of `fn`.
+     */
+    withExecution<T>(fn: () => T): T;
+    /**
+     * Return a shallow copy of this scope's properties.
+     *
+     * @returns A plain object of property key/value pairs.
+     */
+    getProperties(): Properties;
+    /**
+     * Return the protected context bound to this scope, or `null` if none.
+     *
+     * @returns A copy of the protected context, or `null`.
+     */
+    getProtectedContext(): ProtectedContext | null;
+    _getBundleKey(): string;
+    _getSnapshot(): ScopeSnapshot;
+    _belongsTo(client: BaseLiteguardClient): boolean;
+}
+/**
+ * Core Liteguard client that evaluates guards, buffers telemetry signals,
+ * and manages background refresh and flush cycles.
+ *
+ * This is the platform-agnostic base class. Use the platform-specific
+ * `LiteguardClient` from `@liteguard/liteguard-node` or
+ * `@liteguard/liteguard-browser` unless you are providing a custom
+ * {@link RuntimeAdapter}.
+ */
+declare class BaseLiteguardClient {
+    private readonly projectClientKeyId;
+    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;
+    private lifecycleCleanup;
+    private currentRefreshRateSeconds;
+    private readonly rateLimitState;
+    private readonly listeners;
+    /**
+     * Create a new Liteguard client.
+     *
+     * Call {@link start} after construction to fetch the initial guard bundle
+     * 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 options - Optional SDK configuration overrides.
+     */
+    constructor(runtime: RuntimeAdapter, projectClientKeyId: 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
+     * client in production.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop all background timers and flush remaining buffered signals.
+     * After calling `shutdown` the client should not be used further.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Returns `true` once the initial public guard bundle has been fetched.
+     */
+    isReady(): boolean;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const unsubscribe = client.subscribe(() => {
+     *   console.log('Guards refreshed');
+     * });
+     * // later…
+     * unsubscribe();
+     * ```
+     */
+    subscribe(listener: LiteguardChangeListener): () => void;
+    /**
+     * Create a new request scope with optional initial properties. The scope
+     * uses the public guard bundle by default; call
+     * {@link LiteguardScope.bindProtectedContext} on the returned scope to
+     * attach signed user context.
+     *
+     * @param properties - Initial property key/value pairs for the scope.
+     * @returns A new {@link LiteguardScope}.
+     *
+     * @example
+     * ```ts
+     * const scope = client.createScope({ plan: 'enterprise' });
+     * scope.isOpen('feature.beta'); // evaluates with plan=enterprise
+     * ```
+     */
+    createScope(properties?: Properties): LiteguardScope;
+    /**
+     * Return the currently active request scope, or the shared default scope
+     * when no request-local scope is active.
+     *
+     * On Node.js, the active scope is resolved from `AsyncLocalStorage` so
+     * each concurrent request can carry its own context automatically.
+     *
+     * @returns The active {@link LiteguardScope}.
+     */
+    getActiveScope(): LiteguardScope;
+    /**
+     * Run `fn` inside the given request scope. All guard checks performed
+     * during `fn` will use the properties and protected context of `scope`.
+     *
+     * @param scope - The scope to activate.
+     * @param fn - Callback to execute within the scope.
+     * @returns The return value of `fn`.
+     */
+    runWithScope<T>(scope: LiteguardScope, fn: () => T): T;
+    /**
+     * Convenience helper that derives a scope from the current active scope,
+     * merges in the supplied properties, and runs `fn` inside it.
+     *
+     * @param properties - Key/value pairs to add for the duration of `fn`.
+     * @param fn - Callback to execute within the scoped context.
+     * @returns The return value of `fn`.
+     *
+     * @example
+     * ```ts
+     * const result = client.withProperties({ userId: '42' }, () => {
+     *   return client.isOpen('feature.beta');
+     * });
+     * ```
+     */
+    withProperties<T>(properties: Properties, fn: () => T): T;
+    /**
+     * Bind protected context to a derived scope and run `fn` inside it.
+     * Fetches (or reuses) a guard bundle specific to this context before
+     * executing `fn`.
+     *
+     * @param protectedContext - Signed context bundle from your auth backend.
+     * @param fn - Callback to execute within the protected scope.
+     * @returns The (awaited) return value of `fn`.
+     */
+    withProtectedContext<T>(protectedContext: ProtectedContext, fn: () => T | Promise<T>): Promise<Awaited<T>>;
+    /**
+     * Run `fn` inside a Liteguard execution scope so that all guard signals
+     * emitted during `fn` share a common execution ID for correlated
+     * telemetry. If an execution scope is already active, `fn` is called
+     * directly without creating a new one.
+     *
+     * @param fn - Callback to execute within the execution scope.
+     * @returns The return value of `fn`.
+     */
+    withExecution<T>(fn: () => T): T;
+    /**
+     * Return `true` if the named guard is open for the resolved request scope.
+     * Buffers a `guard_check` telemetry signal and consumes a rate-limit slot
+     * when applicable.
+     *
+     * Guards that have not yet been adopted on the Liteguard dashboard always
+     * return `true`, allowing you to instrument code before enabling the guard.
+     *
+     * @param name - Guard name (e.g. `"payments.checkout"`).
+     * @param callOptions - Optional per-call overrides (extra properties, fallback, scope).
+     * @returns `true` if the guard is open, `false` otherwise.
+     */
+    isOpen(name: string, callOptions?: ScopedOptions): boolean;
+    /**
+     * Signal-free variant of {@link isOpen}. Returns the same boolean result
+     * but does **not** emit a telemetry signal or consume a rate-limit slot.
+     * Ideal for render loops or other hot paths where you only need the
+     * boolean value.
+     *
+     * @param name - Guard name to evaluate.
+     * @param callOptions - Optional per-call overrides.
+     * @returns `true` if the guard is open, `false` otherwise.
+     */
+    peekIsOpen(name: string, callOptions?: ScopedOptions): boolean;
+    private evaluateIsOpen;
+    /**
+     * Evaluate the guard and, if open, call `fn` inside a correlated execution
+     * scope. Returns `fn`'s result when the guard is open, or `undefined` when
+     * closed. Emits correlated `guard_check` and `guard_execution` signals.
+     *
+     * @param name - Guard name to evaluate.
+     * @param fn - Synchronous function to invoke when the guard is open.
+     * @param callOptions - Optional per-call overrides.
+     * @returns The return value of `fn`, or `undefined` if the guard is closed.
+     *
+     * @example
+     * ```ts
+     * const banner = client.executeIfOpen('promo.banner', () => {
+     *   return renderPromoBanner();
+     * });
+     * ```
+     */
+    executeIfOpen<T>(name: string, fn: () => T, callOptions?: ScopedOptions): T | undefined;
+    /**
+     * Async variant of {@link executeIfOpen}. Evaluates the guard and, if
+     * open, awaits `fn` inside a correlated execution scope.
+     *
+     * @param name - Guard name to evaluate.
+     * @param fn - Async function to invoke when the guard is open.
+     * @param callOptions - Optional per-call overrides.
+     * @returns The resolved value of `fn`, or `undefined` if the guard is closed.
+     */
+    executeIfOpenAsync<T>(name: string, fn: () => Promise<T>, callOptions?: ScopedOptions): Promise<T | undefined>;
+    private executeIfOpenAsyncWithoutAsyncContext;
+    /**
+     * Merge `properties` into the active scope's property bag and persist
+     * the derived scope as the new active scope. Subsequent {@link isOpen}
+     * calls will include these properties unless overridden per-call.
+     *
+     * @param properties - Key/value pairs to add.
+     * @returns The new active {@link LiteguardScope}.
+     */
+    addProperties(properties: Properties): LiteguardScope;
+    /**
+     * Remove the given property keys from the active scope and persist the
+     * resulting scope.
+     *
+     * @param names - Property keys to remove.
+     * @returns The new active {@link LiteguardScope}.
+     */
+    clearProperties(names: string[]): LiteguardScope;
+    /**
+     * Remove all properties from the active scope and persist the resulting
+     * scope.
+     *
+     * @returns The new active {@link LiteguardScope} with an empty property bag.
+     */
+    resetProperties(): LiteguardScope;
+    /**
+     * Bind protected context to the active scope and persist the derived
+     * scope. Fetches (or reuses) a guard bundle specific to this context.
+     *
+     * @param protectedContext - Signed context bundle from your auth backend.
+     * @returns The new active {@link LiteguardScope}.
+     */
+    bindProtectedContext(protectedContext: ProtectedContext): Promise<LiteguardScope>;
+    /**
+     * Clear protected context from the active scope and revert to the
+     * public guard bundle.
+     *
+     * @returns The new active {@link LiteguardScope}.
+     */
+    clearProtectedContext(): LiteguardScope;
+    /**
+     * Immediately transmit all buffered telemetry signals to the backend. Also
+     * flushes any pending unadopted-guard reports.
+     *
+     * Call this before process exit or page unload to avoid losing signals.
+     *
+     * @param options - Flush options (e.g. `{ keepalive: true }` for page unload).
+     */
+    flushSignals(options?: FlushOptions): Promise<void>;
+    /** Notify subscribers that client-visible state has changed. */
+    protected emitChange(): void;
+    /** @internal Derive a new immutable scope from an existing scope snapshot. */
+    _deriveScope(scope: LiteguardScope, patch: Partial<ScopeSnapshot>): LiteguardScope;
+    /** @internal Bind protected context to a scope and ensure its bundle is loaded. */
+    _bindProtectedContextToScope(scope: LiteguardScope, protectedContext: ProtectedContext): Promise<LiteguardScope>;
+    /** Persist a derived scope into the current request-local or default scope slot. */
+    private replaceCurrentScope;
+    /** Resolve the active runtime scope store into a client-owned scope instance. */
+    private getRuntimeScope;
+    /** Validate and resolve the scope used for a client operation. */
+    private resolveScope;
+    /** Queue a one-time report for a guard that exists only in application code. */
+    private recordUnadoptedGuard;
+    /** Schedule the next periodic guard refresh using the current refresh interval. */
+    private scheduleNextRefresh;
+    /** Refresh every cached bundle once, then reschedule the next cycle. */
+    private runRefreshCycle;
+    /** Create an empty bundle placeholder before the first successful fetch. */
+    private createEmptyBundle;
+    /** Return a cached bundle by key, if present. */
+    private getBundle;
+    /** Resolve the bundle used for a scope, falling back to the public bundle. */
+    private bundleForScope;
+    /** Ensure the bundle for a protected context exists locally and is ready. */
+    private ensureBundleForProtectedContext;
+    /** Use the shortest bundle refresh rate so all cached bundles stay current. */
+    private recomputeRefreshInterval;
+    /** Fetch the latest guard bundle for a bundle key, respecting ETags and timeouts. */
+    private fetchGuardsForBundle;
+    /** Create an `AbortSignal` that cancels an HTTP request after `timeoutMs`. */
+    private createTimeoutSignal;
+    /** Send a JSON POST request to the Liteguard backend with the SDK defaults applied. */
+    private post;
+    /** Buffer a telemetry signal and trigger an eager flush when the batch is full. */
+    private bufferSignal;
+    /** Allocate signal correlation metadata for the current execution context. */
+    private nextSignalMetadata;
+    private runWithExplicitExecutionState;
+    /** Capture the first external stack frame so telemetry can identify the call site. */
+    private captureCallsiteId;
+    /** Build the in-memory rate-limit bucket key for a guard and property set. */
+    private rateLimitBucketKey;
+    private checkRateLimit;
+    /** Check whether a guard would pass the current rate-limit window without consuming a slot. */
+    private wouldPassRateLimit;
+    /** Decide whether performance measurement should be captured for this guard call. */
+    private isMeasurementEnabled;
+    /** Return the hard cap for the in-memory signal buffer after flush failures. */
+    private maxBufferSize;
+    /** Drain and reset the count of dropped signals to attach to the next emitted signal. */
+    private takeDroppedSignals;
+    /** Write a warning only when quiet mode is disabled. */
+    private log;
+    /** @internal Test helper for swapping the public guard bundle in memory. */
+    _setGuards(guards: Guard[]): void;
+    /** @internal Test helper for swapping a protected-context bundle in memory. */
+    _setProtectedGuards(protectedContext: ProtectedContext, guards: Guard[]): void;
+    /** @internal Clear all rate-limit counters, or only those for a specific guard. */
+    _resetRateLimitState(name?: string): void;
+    /** @internal Return the default scope properties for tests and diagnostics. */
+    _getContext(): Properties;
+    /** @internal Return the default scope protected context for tests and diagnostics. */
+    _getProtectedContext(): ProtectedContext | null;
+    /** @internal Return the active refresh cadence for tests and diagnostics. */
+    _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 currently cached bundle keys. */
+    _getBundleKeys(): string[];
+    /** @internal Expose the request-scope store for tests. */
+    _getRequestScopeStore(): RequestScopeStore | undefined;
+}
+
+/**
+ * Evaluate all rules for a guard against the given properties.
+ *
+ * Rules are checked in order; the first matching, enabled rule wins and its
+ * `result` is returned. If no rule matches, the guard's `defaultValue` is
+ * returned instead.
+ *
+ * @param guard - The guard definition containing rules and a default value.
+ * @param properties - The property bag to evaluate each rule against.
+ * @returns `true` if the guard is open (traffic should proceed), `false` otherwise.
+ */
+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 };