@govplane/runtime-sdk 0.2.4

package/dist/index.d.ts

@@ -0,0 +1,413 @@
+type Target = {
+    service: string;
+    resource: string;
+    action: string;
+};
+type Effect = {
+    type: "allow";
+} | {
+    type: "deny";
+} | {
+    type: "kill_switch";
+    killSwitch: {
+        service: string;
+        reason?: string;
+    };
+} | {
+    type: "throttle";
+    throttle: {
+        limit: number;
+        windowSeconds: number;
+        key: string;
+    };
+};
+type WhenAstV1 = {
+    op: "and" | "or";
+    args: WhenAstV1[];
+} | {
+    op: "not";
+    arg: WhenAstV1;
+} | {
+    op: "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+    path: string;
+    value: any;
+} | {
+    op: "in";
+    path: string;
+    values: any[];
+} | {
+    op: "exists";
+    path: string;
+};
+type RuntimeRule = {
+    id: string;
+    status: "active" | "disabled";
+    priority: number;
+    target: Target;
+    when?: WhenAstV1;
+    effect: Effect;
+    description?: string;
+};
+type RuntimePolicy = {
+    policyKey: string;
+    activeVersion: number;
+    defaults: {
+        effect: "allow" | "deny";
+    };
+    rules: RuntimeRule[];
+};
+type RuntimeBundleV1 = {
+    schemaVersion: 1;
+    orgId: string;
+    projectId: string;
+    env: string;
+    generatedAt: string;
+    policies: RuntimePolicy[];
+};
+type Decision = {
+    decision: "allow";
+    reason: "default" | "rule";
+    policyKey?: string;
+    ruleId?: string;
+} | {
+    decision: "deny";
+    reason: "default" | "rule";
+    policyKey?: string;
+    ruleId?: string;
+} | {
+    decision: "kill_switch";
+    reason: "rule";
+    policyKey: string;
+    ruleId: string;
+    killSwitch: {
+        service: string;
+        reason?: string;
+    };
+} | {
+    decision: "throttle";
+    reason: "rule";
+    policyKey: string;
+    ruleId: string;
+    throttle: {
+        limit: number;
+        windowSeconds: number;
+        key: string;
+    };
+};
+type TraceDiscardReason = "disabled" | "target_mismatch" | "when_false" | "invalid_effect";
+type TraceRule = {
+    policyKey: string;
+    ruleId: string;
+    priority: number;
+    effectType?: string;
+    matched: boolean;
+    discardedReason?: TraceDiscardReason;
+};
+type DecisionTrace = {
+    evaluatedAt: string;
+    target: Target;
+    summary: {
+        policiesSeen: number;
+        rulesSeen: number;
+        matched: number;
+        considered: {
+            kill_switch: number;
+            deny: number;
+            throttle: number;
+            allow: number;
+        };
+    };
+    winner?: {
+        policyKey: string;
+        ruleId: string;
+        effectType: string;
+        priority: number;
+    };
+    rules: TraceRule[];
+};
+type DecisionWithTrace = Decision & {
+    trace: DecisionTrace;
+};
+type TraceLevel = "off" | "errors" | "sampled" | "full";
+type TraceMode = "compact" | "full";
+type TraceOptions = {
+    level?: TraceLevel;
+    mode?: TraceMode;
+    sampling?: number;
+    force?: boolean;
+    budget?: {
+        maxTraces: number;
+        windowMs: number;
+    };
+};
+type PolicyEngineEvaluateInput = {
+    target: Target;
+    context?: Record<string, unknown>;
+};
+type PolicyEngine = {
+    evaluate(input: PolicyEngineEvaluateInput): Decision;
+    evaluateWithTrace(input: PolicyEngineEvaluateInput, options?: TraceOptions): DecisionWithOptionalTrace;
+    flushTraces(): Promise<void>;
+};
+type DecisionTraceCompact = {
+    traceId: string;
+    sampled: "forced" | "random";
+    evaluatedAt: string;
+    target: Target;
+    summary: {
+        policiesSeen: number;
+        rulesSeen: number;
+        matched: number;
+        considered: {
+            kill_switch: number;
+            deny: number;
+            throttle: number;
+            allow: number;
+        };
+    };
+    winner?: {
+        policyKey: string;
+        ruleId: string;
+        effectType: string;
+        priority: number;
+    };
+};
+type DecisionTraceFull = DecisionTraceCompact & {
+    rules: TraceRule[];
+};
+type DecisionWithOptionalTrace = Decision & {
+    trace?: DecisionTraceCompact | DecisionTraceFull;
+};
+type StructuredTraceEvent = {
+    v: 1;
+    ts: string;
+    traceId: string;
+    sampled: "forced" | "random" | "errors";
+    level: TraceLevel;
+    target: Target;
+    decision: Decision["decision"];
+    reason: Decision["reason"];
+    winner?: {
+        policyKey: string;
+        ruleId: string;
+        effectType: string;
+        priority: number;
+    };
+    summary: {
+        policiesSeen: number;
+        rulesSeen: number;
+        matched: number;
+        considered: {
+            kill_switch: number;
+            deny: number;
+            throttle: number;
+            allow: number;
+        };
+    };
+    rules?: Array<{
+        policyKey: string;
+        ruleId: string;
+        priority: number;
+        effectType?: string;
+        matched: boolean;
+        discardedReason?: string;
+    }>;
+};
+type TraceSink = (evt: StructuredTraceEvent) => void;
+type TraceSinkAsync = (evt: StructuredTraceEvent) => Promise<void>;
+type TraceQueueDropPolicy = "drop_new" | "drop_old";
+type DecisionTraceHook = (evt: StructuredTraceEvent) => void;
+type RuntimeClientOptions = {
+    trace?: {
+        level?: TraceLevel;
+        sampling?: number;
+        budget?: {
+            maxTraces: number;
+            windowMs: number;
+        };
+        onDecisionTrace?: DecisionTraceHook;
+    };
+};
+
+type ContextPolicy = {
+    allowedKeys: string[];
+    maxStringLen: number;
+    maxArrayLen: number;
+    blockLikelyPiiKeys: boolean;
+};
+declare const DEFAULT_CONTEXT_POLICY: ContextPolicy;
+declare function validateContext(ctx: Record<string, unknown>, policy: ContextPolicy): void;
+
+type RuntimeClientConfig = {
+    baseUrl: string;
+    runtimeKey: string;
+    orgId: string;
+    projectId: string;
+    env: string;
+    pollMs?: number;
+    burstPollMs?: number;
+    burstDurationMs?: number;
+    timeoutMs?: number;
+    userAgent?: string;
+    backoffBaseMs?: number;
+    backoffMaxMs?: number;
+    backoffJitter?: number;
+    degradeAfterFailures?: number;
+    /**
+     * Engine config
+     */
+    engine?: {
+        validateContext?: boolean;
+        contextPolicy?: ContextPolicy;
+    };
+    /**
+     * Decision trace (SDK-only, zero PII)
+     */
+    trace?: {
+        defaults?: TraceOptions;
+        onDecisionTrace?: (evt: StructuredTraceEvent) => void;
+        onDecisionTraceAsync?: (evt: StructuredTraceEvent) => Promise<void>;
+        queueMax?: number;
+        dropPolicy?: "drop_new" | "drop_old";
+        onTraceError?: (err: unknown) => void;
+    };
+    incidentEnvFlag?: string;
+    incidentFilePath?: string;
+    incidentFilePollMs?: number;
+    incidentSignal?: "SIGUSR1" | false;
+};
+type BundleMeta = {
+    etag: string;
+    bundleVersion?: number;
+    updatedAt?: string;
+};
+type RuntimeCache<TBundle = unknown> = {
+    meta?: BundleMeta;
+    bundle?: TBundle;
+};
+type RefreshResult<TBundle = unknown> = {
+    changed: false;
+    meta?: BundleMeta;
+} | {
+    changed: true;
+    meta: BundleMeta;
+    bundle: TBundle;
+};
+type RuntimeStatus = {
+    state: "warming_up";
+} | {
+    state: "ok";
+} | {
+    state: "degraded";
+    consecutiveFailures: number;
+    lastError: {
+        message: string;
+        at: string;
+    };
+    nextRetryAt?: string;
+};
+/**
+ * RuntimeClient = polling/backoff/degraded + cached runtime bundle + policy evaluation.
+ *
+ * - No endpoints expuestos por el cliente
+ * - No PII en trace: el engine emite StructuredTraceEvent sin context ni reglas completas
+ */
+declare class RuntimeClient<TBundle = RuntimeBundleV1> {
+    private readonly cfg;
+    private cache;
+    private timer;
+    private isRunning;
+    private hasValidBundle;
+    private inFlightRefresh;
+    private burstUntil;
+    private consecutiveFailures;
+    private lastError;
+    private nextRetryAtMs;
+    private updateListeners;
+    private statusListeners;
+    private readonly engine;
+    private incidentPollTimer;
+    private incidentFileLastMtimeMs;
+    private installedSignalHandler;
+    private sigHandler?;
+    constructor(config: RuntimeClientConfig);
+    /** Subscribe to bundle updates (only when changed). */
+    onUpdate(fn: (res: Extract<RefreshResult<TBundle>, {
+        changed: true;
+    }>) => void): () => void;
+    /** Subscribe to status changes (ok/degraded). */
+    onStatus(fn: (s: RuntimeStatus) => void): () => void;
+    /** Evaluate a decision using the cached bundle (deny-by-default if bundle missing/invalid). */
+    evaluate(input: {
+        target: Target;
+        context?: Record<string, unknown>;
+    }): Decision;
+    /** Evaluate and (optionally) attach trace based on trace defaults/overrides. */
+    evaluateWithTrace(input: {
+        target: Target;
+        context?: Record<string, unknown>;
+    }, options?: TraceOptions): DecisionWithOptionalTrace;
+    /** Flush async trace queue (only does something if traceSinkAsync is configured). */
+    flushTraces(): Promise<void>;
+    getCached(): RuntimeCache<TBundle>;
+    getStatus(): RuntimeStatus;
+    start(): void;
+    warmStart(opts?: {
+        timeoutMs?: number;
+        burst?: boolean;
+    }): Promise<void>;
+    stop(): void;
+    refreshNow(opts?: {
+        burst?: boolean;
+    }): Promise<RefreshResult<TBundle>>;
+    private emitStatusIfNeeded;
+    private refresh;
+    private scheduleNext;
+    private effectivePollMs;
+    private markSuccess;
+    private markFailure;
+    private computeBackoffDelayMs;
+    private bundleUrl;
+    private commonHeaders;
+    private headBundle;
+    private getBundle;
+    private enableBurst;
+    private disableBurst;
+    private applyIncidentFromEnv;
+    private startIncidentFilePoller;
+    private checkIncidentFileOnce;
+    private installIncidentSignal;
+    private uninstallIncidentSignal;
+}
+
+declare class GovplaneError extends Error {
+    readonly code: string;
+    readonly details?: any | undefined;
+    constructor(message: string, code?: string, details?: any | undefined);
+}
+declare class HttpError extends GovplaneError {
+    readonly status: number;
+    readonly headers?: Record<string, string> | undefined;
+    constructor(message: string, status: number, headers?: Record<string, string> | undefined, details?: any);
+}
+
+type EngineOpts = {
+    getBundle: () => RuntimeBundleV1 | undefined;
+    validateContext?: boolean;
+    contextPolicy?: ContextPolicy;
+    traceDefaults?: TraceOptions;
+    traceSink?: TraceSink;
+    traceSinkAsync?: TraceSinkAsync;
+    traceQueueMax?: number;
+    traceQueueDropPolicy?: TraceQueueDropPolicy;
+    onTraceSinkError?: (err: unknown) => void;
+};
+declare function createPolicyEngine(opts: EngineOpts): PolicyEngine;
+
+type FormatOpts = {
+    multiline?: boolean;
+    includeDiscarded?: boolean;
+};
+declare function formatTrace(trace: DecisionTraceCompact | DecisionTraceFull, opts?: FormatOpts): string;
+
+export { type BundleMeta, type ContextPolicy, DEFAULT_CONTEXT_POLICY, type Decision, type DecisionTrace, type DecisionTraceCompact, type DecisionTraceFull, type DecisionTraceHook, type DecisionWithOptionalTrace, type DecisionWithTrace, type Effect, GovplaneError, HttpError, type PolicyEngine, type PolicyEngineEvaluateInput, type RefreshResult, type RuntimeBundleV1, type RuntimeCache, RuntimeClient, type RuntimeClientConfig, type RuntimeClientOptions, type RuntimePolicy, type RuntimeRule, type RuntimeStatus, type StructuredTraceEvent, type Target, type TraceDiscardReason, type TraceLevel, type TraceMode, type TraceOptions, type TraceQueueDropPolicy, type TraceRule, type TraceSink, type TraceSinkAsync, type WhenAstV1, createPolicyEngine, formatTrace, validateContext };