@spfn/monitor 0.1.0-beta.1

package/dist/server.d.ts

@@ -0,0 +1,518 @@
+import { E as ErrorGroupStatus, c as ErrorGroup, N as NewErrorGroup, L as LogLevel, d as NewLog, e as Log } from './index-C9IUDNIv.js';
+export { a as ERROR_GROUP_STATUSES, b as LOG_LEVELS, M as MonitorStats, f as errorGroups, g as getMonitorStats, l as logs, m as monitorRouter } from './index-C9IUDNIv.js';
+import { BaseRepository } from '@spfn/core/db';
+import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
+import * as _spfn_core_logger from '@spfn/core/logger';
+import '@spfn/core/route';
+import '@sinclair/typebox';
+
+/**
+ * @spfn/monitor - Database Schema Definition
+ *
+ * Defines the 'spfn_monitor' PostgreSQL schema for all monitor-related tables
+ */
+/**
+ * Monitor schema for all monitoring tables
+ * Tables: error_groups, error_events, logs
+ */
+declare const monitorSchema: drizzle_orm_pg_core.PgSchema<string>;
+
+/**
+ * @spfn/monitor - Error Events Entity
+ *
+ * Individual error occurrences linked to an error group.
+ * Stores request-specific context (headers, query, stack trace).
+ */
+/**
+ * Error events table — individual error occurrences
+ */
+declare const errorEvents: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "error_events";
+    schema: string;
+    columns: {
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "error_events";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "error_events";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "error_events";
+            dataType: "number";
+            columnType: "PgBigSerial53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        groupId: drizzle_orm_pg_core.PgColumn<{
+            name: `${string}_id`;
+            tableName: "error_events";
+            dataType: "number";
+            columnType: "PgBigSerial53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        requestId: drizzle_orm_pg_core.PgColumn<{
+            name: "request_id";
+            tableName: "error_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: drizzle_orm_pg_core.PgColumn<{
+            name: "user_id";
+            tableName: "error_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        statusCode: drizzle_orm_pg_core.PgColumn<{
+            name: "status_code";
+            tableName: "error_events";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        headers: drizzle_orm_pg_core.PgColumn<{
+            name: "headers";
+            tableName: "error_events";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, string>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, string>;
+        }>;
+        query: drizzle_orm_pg_core.PgColumn<{
+            name: "query";
+            tableName: "error_events";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, string>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, string>;
+        }>;
+        stackTrace: drizzle_orm_pg_core.PgColumn<{
+            name: "stack_trace";
+            tableName: "error_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        metadata: drizzle_orm_pg_core.PgColumn<{
+            name: "metadata";
+            tableName: "error_events";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, unknown>;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, unknown>;
+        }>;
+    };
+    dialect: "pg";
+}>;
+type ErrorEvent = typeof errorEvents.$inferSelect;
+type NewErrorEvent = typeof errorEvents.$inferInsert;
+
+/**
+ * @spfn/monitor - Error Tracking Service
+ *
+ * Core service for tracking errors with fingerprint-based deduplication.
+ * Uses DB state transitions (new/reopened) instead of in-memory throttling
+ * to determine when Slack notifications should be sent.
+ */
+
+/**
+ * Context from the error handler middleware
+ */
+interface ErrorTrackingContext {
+    statusCode: number;
+    path: string;
+    method: string;
+    requestId?: string;
+    userId?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+}
+/**
+ * Generate a deterministic fingerprint for error deduplication
+ *
+ * SHA-256 of (name:message:path), first 16 hex characters
+ */
+declare function generateFingerprint(name: string, message: string, path: string): string;
+/**
+ * Track an error occurrence
+ *
+ * 1. Generate fingerprint
+ * 2. Find or create error group
+ * 3. Create error event
+ * 4. Send Slack notification on new or reopened errors
+ */
+declare function trackError(err: Error, ctx: ErrorTrackingContext, metadata?: Record<string, unknown>): Promise<void>;
+/**
+ * Update error group status with validation
+ */
+declare function updateErrorGroupStatus(groupId: number, newStatus: ErrorGroupStatus): Promise<ErrorGroup>;
+
+/**
+ * Error Groups Repository
+ *
+ * Data access for error group management with read/write splitting
+ */
+
+interface ErrorGroupFilters {
+    status?: ErrorGroupStatus;
+    path?: string;
+    search?: string;
+    dateFrom?: Date;
+    dateTo?: Date;
+    limit?: number;
+    offset?: number;
+}
+declare class ErrorGroupsRepository extends BaseRepository {
+    findById(id: number): Promise<ErrorGroup | null>;
+    findByFingerprint(fingerprint: string): Promise<ErrorGroup | null>;
+    findMany(filters?: ErrorGroupFilters): Promise<ErrorGroup[]>;
+    create(data: NewErrorGroup): Promise<ErrorGroup>;
+    incrementCount(id: number): Promise<ErrorGroup | null>;
+    updateStatus(id: number, status: ErrorGroupStatus): Promise<ErrorGroup | null>;
+    countByStatus(): Promise<Record<ErrorGroupStatus, number>>;
+}
+declare const errorGroupsRepository: ErrorGroupsRepository;
+
+/**
+ * Error Events Repository
+ *
+ * Data access for individual error event records
+ */
+
+declare class ErrorEventsRepository extends BaseRepository {
+    create(data: NewErrorEvent): Promise<ErrorEvent>;
+    findByGroupId(groupId: number, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ErrorEvent[]>;
+    deleteOlderThan(date: Date): Promise<number>;
+}
+declare const errorEventsRepository: ErrorEventsRepository;
+
+/**
+ * Logs Repository
+ *
+ * Data access for developer log entries
+ */
+
+interface LogFilters {
+    level?: LogLevel;
+    source?: string;
+    search?: string;
+    requestId?: string;
+    userId?: string;
+    dateFrom?: Date;
+    dateTo?: Date;
+    limit?: number;
+    offset?: number;
+}
+declare class LogsRepository extends BaseRepository {
+    create(data: NewLog): Promise<Log>;
+    findMany(filters?: LogFilters): Promise<Log[]>;
+    countByLevel(): Promise<Record<LogLevel, number>>;
+    deleteOlderThan(date: Date): Promise<number>;
+}
+declare const logsRepository: LogsRepository;
+
+/**
+ * @spfn/monitor - Log Service
+ *
+ * Pluggable log storage with DB as default implementation.
+ * Use setLogStore() to swap to S3, ClickHouse, etc.
+ */
+
+/**
+ * Log store interface — implement for custom storage backends
+ */
+interface LogStore {
+    write(entry: NewLog): Promise<Log>;
+    query(filters: LogFilters): Promise<Log[]>;
+    purge(olderThan: Date): Promise<number>;
+}
+/**
+ * Replace the default log store with a custom implementation
+ */
+declare function setLogStore(store: LogStore): void;
+/**
+ * Get the current log store
+ */
+declare function getLogStore(): LogStore;
+/**
+ * Write params for public API
+ */
+interface WriteLogParams {
+    level: LogLevel;
+    message: string;
+    source?: string;
+    requestId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Write a log entry
+ */
+declare function writeLog(params: WriteLogParams): Promise<Log>;
+/**
+ * Query logs with filters
+ */
+declare function queryLogs(filters: LogFilters): Promise<Log[]>;
+
+/**
+ * @spfn/monitor - Error Handler Integration
+ *
+ * Drop-in replacement for createErrorSlackNotifier from @spfn/notification.
+ * Uses DB-backed error tracking with state-based notifications instead of
+ * in-memory time-based throttling.
+ *
+ * @example
+ * ```typescript
+ * import { createMonitorErrorHandler } from '@spfn/monitor/server';
+ *
+ * export default defineServerConfig()
+ *     .middleware({ onError: createMonitorErrorHandler() })
+ *     .build();
+ * ```
+ */
+
+interface MonitorErrorHandlerOptions {
+    /**
+     * Minimum status code to track
+     * @default env.SPFN_MONITOR_MIN_STATUS_CODE or 500
+     */
+    minStatusCode?: number;
+    /**
+     * Extract custom metadata from error and context
+     */
+    extractMetadata?: (err: Error, ctx: ErrorTrackingContext) => Record<string, unknown>;
+}
+interface OnErrorContext {
+    statusCode: number;
+    path: string;
+    method: string;
+    requestId?: string;
+    timestamp: string;
+    userId?: string;
+    request: {
+        headers: Record<string, string>;
+        query: Record<string, string>;
+    };
+}
+/**
+ * Create an onError callback that tracks errors in DB and sends Slack notifications
+ *
+ * Returns a function matching ErrorHandler's onError signature.
+ * Replaces createErrorSlackNotifier from @spfn/notification.
+ */
+declare function createMonitorErrorHandler(options?: MonitorErrorHandlerOptions): (err: Error, ctx: OnErrorContext) => Promise<void>;
+
+/**
+ * @spfn/monitor - Server Lifecycle Hooks
+ *
+ * Provides lifecycle hooks for SPFN server initialization
+ */
+/**
+ * Monitor lifecycle configuration
+ */
+interface MonitorLifecycleConfig {
+    afterInfrastructure?: () => Promise<void>;
+}
+/**
+ * Create monitor lifecycle hooks for server configuration
+ *
+ * @example
+ * ```typescript
+ * import { defineServerConfig } from '@spfn/core/server';
+ * import { createMonitorLifecycle, monitorRouter } from '@spfn/monitor/server';
+ *
+ * export default defineServerConfig()
+ *     .routes(appRouter)
+ *     .lifecycle(createMonitorLifecycle())
+ *     .build();
+ * ```
+ */
+declare function createMonitorLifecycle(): MonitorLifecycleConfig;
+
+/**
+ * @spfn/monitor - Centralized Logger
+ *
+ * All monitor package loggers with consistent naming
+ */
+declare const monitorLogger: {
+    errorTracking: _spfn_core_logger.Logger;
+    logging: _spfn_core_logger.Logger;
+    notification: _spfn_core_logger.Logger;
+    lifecycle: _spfn_core_logger.Logger;
+    route: _spfn_core_logger.Logger;
+};
+
+/**
+ * @spfn/monitor/server
+ *
+ * Server-side Only Module
+ *
+ * Includes:
+ * - Router (admin endpoints)
+ * - Repositories (error groups, events, logs)
+ * - Services (error tracking, logging, stats)
+ * - Integrations (error handler, lifecycle)
+ * - Entities
+ *
+ * @example
+ * ```typescript
+ * import {
+ *     createMonitorErrorHandler,
+ *     createMonitorLifecycle,
+ *     monitorRouter,
+ *     writeLog,
+ * } from '@spfn/monitor/server';
+ *
+ * export default defineServerConfig()
+ *     .middleware({ onError: createMonitorErrorHandler() })
+ *     .routes(mergeRouters(appRouter, monitorRouter))
+ *     .lifecycle(createMonitorLifecycle())
+ *     .build();
+ * ```
+ */
+
+/**
+ * Convenience namespace for quick logging
+ *
+ * @example
+ * ```typescript
+ * import { monitor } from '@spfn/monitor/server';
+ *
+ * await monitor.log({
+ *     level: 'info',
+ *     message: 'User signed up',
+ *     source: 'auth',
+ *     metadata: { userId: 123 },
+ * });
+ * ```
+ */
+declare const monitor: {
+    log: typeof writeLog;
+};
+
+export { type ErrorEvent, ErrorGroup, type ErrorGroupFilters, ErrorGroupStatus, type ErrorTrackingContext, Log, type LogFilters, LogLevel, type LogStore, type MonitorErrorHandlerOptions, type NewErrorEvent, NewErrorGroup, NewLog, type WriteLogParams, createMonitorErrorHandler, createMonitorLifecycle, errorEvents, errorEventsRepository, errorGroupsRepository, generateFingerprint, getLogStore, logsRepository, monitor, monitorLogger, monitorSchema, queryLogs, setLogStore, trackError, updateErrorGroupStatus, writeLog };