@a-company/sentinel 0.2.0 → 3.5.0

package/dist/storage-BqCJqZat.d.ts

@@ -0,0 +1,129 @@
+import { l as CreateIncidentInput, a as SymbolicIncidentRecord, w as IncidentQueryOptions, v as IncidentNote, m as CreatePatternInput, e as FailurePattern, Z as PatternQueryOptions, k as CreateGroupInput, I as IncidentGroup, ab as ResolutionQueryOptions, ac as ResolutionRecord, b as SentinelStats, c as SymbolHealth, f as PatternExport, B as BackupExport, a5 as PracticeEventInput, a6 as PracticeEventQuery, a4 as PracticeEvent, y as LogEntryInput, G as LogQueryOptions, L as LogEntry, ag as ServiceRegistration, af as ServiceInfo, A as AppState, Q as MetricInput, R as MetricQueryOptions, O as MetricEntry, N as MetricAggregation, an as TraceSpanInput, ao as TraceView } from './types-BmVoO1iF.js';
+
+/**
+ * Paradigm Sentinel - SQLite Storage Layer
+ *
+ * Persistent storage for incidents, patterns, groups, and resolutions.
+ * Uses sql.js for pure JavaScript SQLite (no native compilation needed).
+ */
+
+declare class SentinelStorage {
+    private db;
+    private dbPath;
+    private incidentCounter;
+    private initialized;
+    constructor(dbPath?: string);
+    private getDefaultDbPath;
+    private createSchema;
+    private save;
+    recordIncident(input: CreateIncidentInput): string;
+    private initializeSync;
+    /**
+     * Run schema migrations from older versions
+     */
+    private migrateSchema;
+    /**
+     * Ensure the storage is ready for use. Must be called once before using storage methods.
+     */
+    ensureReady(): Promise<void>;
+    getIncident(id: string): SymbolicIncidentRecord | null;
+    getRecentIncidents(options?: IncidentQueryOptions): SymbolicIncidentRecord[];
+    updateIncident(id: string, updates: Partial<SymbolicIncidentRecord>): void;
+    addIncidentNote(incidentId: string, note: Omit<IncidentNote, 'id'>): void;
+    linkIncidents(incidentId: string, relatedId: string): void;
+    getIncidentCount(options?: IncidentQueryOptions): number;
+    addPattern(input: CreatePatternInput): string;
+    getPattern(id: string): FailurePattern | null;
+    getAllPatterns(options?: PatternQueryOptions): FailurePattern[];
+    updatePattern(id: string, updates: Partial<FailurePattern>): void;
+    deletePattern(id: string): void;
+    updatePatternConfidence(patternId: string, event: 'matched' | 'resolved' | 'recurred'): void;
+    createGroup(input: CreateGroupInput): string;
+    getGroup(id: string): IncidentGroup | null;
+    getGroups(options?: {
+        limit?: number;
+    }): IncidentGroup[];
+    addToGroup(groupId: string, incidentId: string): void;
+    recordResolution(resolution: {
+        incidentId: string;
+        patternId?: string;
+        commitHash?: string;
+        prUrl?: string;
+        notes?: string;
+    }): void;
+    markRecurred(incidentId: string): void;
+    getResolutionHistory(options?: ResolutionQueryOptions): ResolutionRecord[];
+    getStats(period: {
+        start: string;
+        end: string;
+    }): SentinelStats;
+    getSymbolHealth(symbol: string): SymbolHealth;
+    exportPatterns(options?: {
+        includePrivate?: boolean;
+    }): PatternExport;
+    importPatterns(data: PatternExport, options?: {
+        overwrite?: boolean;
+    }): {
+        imported: number;
+        skipped: number;
+    };
+    exportBackup(): BackupExport;
+    importBackup(data: BackupExport): void;
+    private rowToIncident;
+    private rowToPattern;
+    private rowToGroup;
+    recordPracticeEvent(input: PracticeEventInput): string;
+    getPracticeEvents(options?: PracticeEventQuery): PracticeEvent[];
+    getPracticeEventCount(options?: PracticeEventQuery): number;
+    getComplianceRate(options?: PracticeEventQuery): {
+        total: number;
+        followed: number;
+        skipped: number;
+        partial: number;
+        rate: number;
+    };
+    private rowToPracticeEvent;
+    private inferSymbolType;
+    insertLog(input: LogEntryInput): string;
+    insertLogBatch(entries: LogEntryInput[]): {
+        accepted: number;
+        errors: string[];
+    };
+    queryLogs(options?: LogQueryOptions): LogEntry[];
+    getLogCount(options?: LogQueryOptions): number;
+    pruneLogs(maxCount: number): number;
+    private rowToLogEntry;
+    registerService(reg: ServiceRegistration): void;
+    updateServiceLastSeen(name: string): void;
+    getServices(): ServiceInfo[];
+    upsertAppState(state: AppState): void;
+    getAppState(service: string, sessionId?: string): AppState[];
+    getAllAppStates(): AppState[];
+    private rowToAppState;
+    insertMetric(input: MetricInput): string;
+    insertMetricBatch(entries: MetricInput[]): {
+        accepted: number;
+        errors: string[];
+    };
+    queryMetrics(options?: MetricQueryOptions): MetricEntry[];
+    getMetricCount(options?: MetricQueryOptions): number;
+    aggregateMetric(name: string, options?: {
+        service?: string;
+        since?: string;
+        until?: string;
+    }): MetricAggregation;
+    pruneMetrics(maxCount: number): number;
+    private rowToMetricEntry;
+    insertSpan(input: TraceSpanInput): string;
+    getTrace(traceId: string): TraceView | null;
+    queryTraces(options?: {
+        service?: string;
+        symbol?: string;
+        since?: string;
+        limit?: number;
+    }): TraceView[];
+    private rowToTraceSpan;
+    close(): void;
+}
+
+export { SentinelStorage as S };

package/dist/transport-DqamniUy.d.ts

@@ -0,0 +1,185 @@
+import { z as LogLevel, Q as MetricInput } from './types-BmVoO1iF.js';
+
+/**
+ * Sentinel Client SDK
+ *
+ * Lightweight client for sending structured logs to the Sentinel server.
+ * Features batching, ring buffer, auto-retry, and graceful degradation.
+ *
+ * Usage:
+ *   import { createSentinelClient } from '@a-company/sentinel';
+ *   const client = createSentinelClient({ service: 'my-app' });
+ *   client.info('#checkout', 'Order placed', { orderId: '123' });
+ *   await client.close();
+ */
+
+interface SentinelClientOptions {
+    /** Sentinel server URL (default: http://localhost:3838) */
+    url?: string;
+    /** Service name (required) */
+    service: string;
+    /** Service version */
+    version?: string;
+    /** Environment (development, staging, production) */
+    environment?: string;
+    /** Auth token for protected servers */
+    token?: string;
+    /** Batch size before auto-flush (default: 50) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 5000) */
+    flushIntervalMs?: number;
+    /** Max entries in ring buffer before dropping oldest (default: 1000) */
+    maxBufferSize?: number;
+    /** Max retry attempts on network failure (default: 3) */
+    maxRetries?: number;
+    /** Retry backoff base in ms (default: 1000) */
+    retryBackoffMs?: number;
+    /** Callback when entries are dropped from buffer overflow */
+    onDrop?: (count: number) => void;
+    /** Callback on flush error */
+    onError?: (error: Error) => void;
+}
+interface SpanContext {
+    traceId: string;
+    spanId: string;
+    end: (status?: 'ok' | 'error') => Promise<void>;
+}
+declare class SentinelClient {
+    private readonly url;
+    private readonly service;
+    private readonly version;
+    private readonly environment;
+    private readonly token;
+    private readonly batchSize;
+    private readonly maxBufferSize;
+    private readonly maxRetries;
+    private readonly retryBackoffMs;
+    private readonly onDrop;
+    private readonly onError;
+    private readonly sessionId;
+    private logBuffer;
+    private metricsBuffer;
+    private flushTimer;
+    private closed;
+    private beforeUnloadHandler;
+    constructor(options: SentinelClientOptions);
+    /** Log a debug-level message */
+    debug(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log an info-level message */
+    info(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log a warn-level message */
+    warn(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log an error-level message */
+    error(symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Log a message at the specified level */
+    log(level: LogLevel, symbol: string, message: string, data?: Record<string, unknown>): void;
+    /** Record a counter metric (increments) */
+    counter(name: string, value?: number, tags?: Record<string, string>): void;
+    /** Record a gauge metric (current value) */
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    /** Record a histogram metric (distribution) */
+    histogram(name: string, value: number, tags?: Record<string, string>): void;
+    /** Record a metric of any type */
+    metric(input: Omit<MetricInput, 'service'>): void;
+    /** Push an application state snapshot to the server */
+    pushState(state: Record<string, unknown>, activeFlows?: string[], activeGates?: string[]): Promise<void>;
+    /** Start a trace span. Call end() on the returned SpanContext when the operation completes. */
+    startSpan(symbol: string, operation: string, parentSpanId?: string): SpanContext;
+    /** Flush all buffered logs and metrics to the server */
+    flush(): Promise<void>;
+    /** Flush remaining entries and shut down the client */
+    close(): Promise<void>;
+    /** Get the session ID assigned to this client instance */
+    getSessionId(): string;
+    /**
+     * Synchronous best-effort flush using sendBeacon (browser) or sync XHR fallback.
+     * Used in beforeunload where async is unreliable.
+     */
+    private flushSync;
+    /** Register this service with the Sentinel server (fire-and-forget) */
+    private registerService;
+    /** Push a log entry into the ring buffer, enforcing maxBufferSize */
+    private pushToLogBuffer;
+    /** Push a metric entry into the ring buffer, enforcing maxBufferSize */
+    private pushToMetricsBuffer;
+    /** Drain and return all entries from the log buffer */
+    private drainLogBuffer;
+    /** Drain and return all entries from the metrics buffer */
+    private drainMetricsBuffer;
+    /** Send log entries to the server with retry */
+    private sendLogs;
+    /** Send metric entries to the server with retry */
+    private sendMetrics;
+    /**
+     * POST JSON to the Sentinel server with exponential backoff retry.
+     * Retries on network errors and 5xx responses. Does NOT retry on 4xx.
+     */
+    private post;
+    /** Get the fetch function, falling back to globalThis.fetch */
+    private getFetch;
+    /** Wait with exponential backoff */
+    private backoff;
+    /** Handle an error, calling the onError callback if provided */
+    private handleError;
+}
+/**
+ * Create a new SentinelClient instance.
+ *
+ * Usage:
+ *   const client = createSentinelClient({ service: 'my-app', environment: 'production' });
+ *   client.info('#checkout', 'Order placed', { orderId: '123' });
+ */
+declare function createSentinelClient(options: SentinelClientOptions): SentinelClient;
+
+/**
+ * SentinelTransport — Bridge between Paradigm Logger and Sentinel Client
+ *
+ * Uses structural typing to match LogTransport interface without
+ * importing from @a-company/paradigm-logger (avoids hard dependency).
+ *
+ * Usage:
+ *   import { enableSentinel } from '@a-company/sentinel/transport';
+ *   import { log } from '@a-company/paradigm-logger';
+ *   enableSentinel(log, { service: 'my-app' });
+ */
+
+/** Structurally matches LogTransport.send() entry shape */
+interface LogEntry {
+    level: string;
+    symbol: string;
+    symbolType: string;
+    message: string;
+    data?: Record<string, unknown>;
+    correlationId?: string;
+    timestamp: string;
+}
+/** Structurally matches ParadigmLogger.addTransport() */
+interface LoggerWithTransports {
+    addTransport(transport: {
+        send(entry: LogEntry): void;
+    }): void;
+    removeTransport(transport: {
+        send(entry: LogEntry): void;
+    }): void;
+}
+declare class SentinelTransport {
+    readonly client: SentinelClient;
+    constructor(client: SentinelClient);
+    send(entry: LogEntry): void;
+}
+/**
+ * Create a SentinelTransport from an existing client or options.
+ *
+ *   const transport = createSentinelTransport(client);
+ *   log.addTransport(transport);
+ */
+declare function createSentinelTransport(clientOrOptions: SentinelClient | SentinelClientOptions): SentinelTransport;
+/**
+ * One-line setup: creates a SentinelTransport and attaches it to a logger.
+ *
+ *   import { log } from '@a-company/paradigm-logger';
+ *   const transport = enableSentinel(log, { service: 'my-app' });
+ */
+declare function enableSentinel(logger: LoggerWithTransports, clientOrOptions: SentinelClient | SentinelClientOptions): SentinelTransport;
+
+export { SentinelClient as S, type SentinelClientOptions as a, SentinelTransport as b, type SpanContext as c, createSentinelClient as d, createSentinelTransport as e, enableSentinel as f };

package/dist/transport.d.ts

@@ -0,0 +1,2 @@
+export { b as SentinelTransport, e as createSentinelTransport, f as enableSentinel } from './transport-DqamniUy.js';
+import './types-BmVoO1iF.js';

package/dist/transport.js

@@ -0,0 +1,10 @@
+import {
+  SentinelTransport,
+  createSentinelTransport,
+  enableSentinel
+} from "./chunk-VQ3SIN7S.js";
+export {
+  SentinelTransport,
+  createSentinelTransport,
+  enableSentinel
+};