@spfn/monitor 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 INFLIKE Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# @spfn/monitor
+
+Error tracking, log management, and monitoring dashboard for SPFN applications.
+
+## Features
+
+- **DB-backed error tracking**: Fingerprint-based deduplication with automatic grouping
+- **State-based notifications**: Slack alerts only on new errors and reopened errors (no duplicates)
+- **Developer logging**: Pluggable log storage with DB default
+- **Admin API**: Superadmin-only routes for managing errors and viewing logs
+- **React dashboard**: Ready-to-use monitoring UI components
+
+## Installation
+
+```bash
+pnpm add @spfn/monitor
+```
+
+## Quick Start
+
+### Server Configuration
+
+```typescript
+import { defineServerConfig } from '@spfn/core/server';
+import { createMonitorErrorHandler, createMonitorLifecycle, monitorRouter } from '@spfn/monitor/server';
+
+export default defineServerConfig()
+    .middleware({ onError: createMonitorErrorHandler() })
+    .routes(appRouter)
+    .lifecycle(createMonitorLifecycle())
+    .build();
+```
+
+Register the monitor router as a package router:
+
+```typescript
+import { monitorRouter } from '@spfn/monitor/server';
+
+export const appRouter = defineRouter({ ... })
+    .packages([authRouter, monitorRouter]);
+```
+
+### Database Migration
+
+```bash
+spfn db migrate
+```
+
+This creates the `spfn_monitor` schema with `error_groups`, `error_events`, and `logs` tables.
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Slack webhook for error notifications (optional)
+SPFN_MONITOR_SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
+
+# Error retention in days (default: 90)
+SPFN_MONITOR_ERROR_RETENTION_DAYS=90
+
+# Log retention in days (default: 30)
+SPFN_MONITOR_LOG_RETENTION_DAYS=30
+
+# Minimum HTTP status code to track (default: 500)
+SPFN_MONITOR_MIN_STATUS_CODE=500
+```
+
+### Code Configuration
+
+```typescript
+import { configureMonitor } from '@spfn/monitor/config';
+
+configureMonitor({
+    slackWebhookUrl: 'https://hooks.slack.com/services/...',
+    errorRetentionDays: 90,
+    logRetentionDays: 30,
+    minStatusCode: 500,
+});
+```
+
+## Error Tracking
+
+Errors are automatically tracked when using `createMonitorErrorHandler()`:
+
+1. **New error** - Creates error group + event, sends Slack notification
+2. **Repeated error** (active/ignored) - Increments count, records event, no notification
+3. **Reopened error** (was resolved) - Changes status to active, sends Slack notification
+
+### Fingerprinting
+
+Errors are grouped by a SHA-256 fingerprint of `name:message:path`, producing a 16-character hex ID.
+
+### Manual Error Tracking
+
+```typescript
+import { trackError } from '@spfn/monitor/server';
+
+await trackError(error, {
+    statusCode: 500,
+    path: '/api/example',
+    method: 'POST',
+    requestId: 'req_123',
+});
+```
+
+## Developer Logging
+
+```typescript
+import { writeLog, queryLogs } from '@spfn/monitor/server';
+
+// Write a log entry
+await writeLog({
+    level: 'info',
+    message: 'User signed in',
+    source: 'auth',
+    userId: 'user_123',
+    metadata: { provider: 'google' },
+});
+
+// Query logs
+const logs = await queryLogs({
+    level: 'error',
+    source: 'payment',
+    limit: 50,
+});
+```
+
+### Custom Log Store
+
+Replace the default DB storage with a custom implementation:
+
+```typescript
+import { setLogStore } from '@spfn/monitor/server';
+
+setLogStore({
+    async write(entry) { /* S3, ClickHouse, etc. */ },
+    async query(filters) { /* ... */ },
+    async purge(olderThan) { /* ... */ },
+});
+```
+
+## Admin API Routes
+
+All routes require `superadmin` role authentication.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/_monitor/admin/errors` | List error groups (filter by status, path, search) |
+| GET | `/_monitor/admin/errors/:id` | Error group detail + recent events |
+| PATCH | `/_monitor/admin/errors/:id` | Update error status (resolve/ignore/reopen) |
+| GET | `/_monitor/admin/errors/:id/events` | List events for an error group |
+| GET | `/_monitor/admin/logs` | Query logs (filter by level, source, search) |
+| GET | `/_monitor/admin/stats` | Dashboard statistics |
+
+## Dashboard Components
+
+```typescript
+// In your Next.js page
+import { MonitorDashboard } from '@spfn/monitor/nextjs/client';
+
+export default function MonitorPage() {
+    return <MonitorDashboard />;
+}
+```
+
+Available components:
+
+- `MonitorDashboard` - Full dashboard with tabs (errors, logs) and stats
+- `StatsOverview` - Error/log count cards with trends
+- `ErrorListView` - Filterable error group table
+- `ErrorDetailView` - Error detail with event timeline and status actions
+- `LogViewer` - Searchable log list with expandable metadata
+
+## API Client
+
+```typescript
+import { monitorApi } from '@spfn/monitor';
+
+// Get dashboard stats
+const stats = await monitorApi.getStats.call({});
+
+// List active errors
+const errors = await monitorApi.listErrors.call({
+    query: { status: 'active', limit: 20 },
+});
+
+// Resolve an error
+await monitorApi.updateErrorStatus.call({
+    params: { id: 1 },
+    body: { status: 'resolved' },
+});
+```
+
+## Exports
+
+```typescript
+// From '@spfn/monitor'
+export { monitorApi };
+export type { MonitorRouter, MonitorStats, ErrorGroupStatus, LogLevel };
+
+// From '@spfn/monitor/server'
+export {
+    // Integration
+    monitorRouter,
+    createMonitorErrorHandler,
+    createMonitorLifecycle,
+
+    // Services
+    trackError, updateErrorGroupStatus,
+    writeLog, queryLogs,
+    getMonitorStats,
+    setLogStore,
+
+    // Entities & Repositories
+    errorGroups, errorEvents, logs,
+    errorGroupsRepository, errorEventsRepository, logsRepository,
+};
+
+// From '@spfn/monitor/config'
+export { configureMonitor };
+
+// From '@spfn/monitor/nextjs/client'
+export {
+    MonitorDashboard, StatsOverview,
+    ErrorListView, ErrorDetailView, LogViewer,
+};
+```
+
+## License
+
+MIT

package/dist/config/index.d.ts

@@ -0,0 +1,136 @@
+import * as _spfn_core_env from '@spfn/core/env';
+
+/**
+ * @spfn/monitor - Environment Schema
+ */
+declare const monitorEnvSchema: {
+    SPFN_MONITOR_SLACK_WEBHOOK_URL: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_MONITOR_SLACK_WEBHOOK_URL";
+    };
+    SPFN_MONITOR_ERROR_RETENTION_DAYS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_MONITOR_ERROR_RETENTION_DAYS";
+    };
+    SPFN_MONITOR_LOG_RETENTION_DAYS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_MONITOR_LOG_RETENTION_DAYS";
+    };
+    SPFN_MONITOR_MIN_STATUS_CODE: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_MONITOR_MIN_STATUS_CODE";
+    };
+};
+
+declare const env: _spfn_core_env.InferEnvType<{
+    SPFN_MONITOR_SLACK_WEBHOOK_URL: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+    } & {
+        key: "SPFN_MONITOR_SLACK_WEBHOOK_URL";
+    };
+    SPFN_MONITOR_ERROR_RETENTION_DAYS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_MONITOR_ERROR_RETENTION_DAYS";
+    };
+    SPFN_MONITOR_LOG_RETENTION_DAYS: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_MONITOR_LOG_RETENTION_DAYS";
+    };
+    SPFN_MONITOR_MIN_STATUS_CODE: {
+        description: string;
+        default: number;
+        required: boolean;
+        examples: number[];
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "SPFN_MONITOR_MIN_STATUS_CODE";
+    };
+}>;
+/**
+ * Monitor configuration
+ */
+interface MonitorConfig {
+    /**
+     * Slack webhook URL override
+     */
+    slackWebhookUrl?: string;
+    /**
+     * Error retention days
+     * @default 90
+     */
+    errorRetentionDays?: number;
+    /**
+     * Log retention days
+     * @default 30
+     */
+    logRetentionDays?: number;
+    /**
+     * Minimum HTTP status code to track
+     * @default 500
+     */
+    minStatusCode?: number;
+}
+/**
+ * Configure monitor settings
+ */
+declare function configureMonitor(config: MonitorConfig): void;
+/**
+ * Get current monitor configuration
+ */
+declare function getMonitorConfig(): MonitorConfig;
+/**
+ * Get Slack webhook URL (config > env)
+ */
+declare function getSlackWebhookUrl(): string | undefined;
+/**
+ * Get error retention days
+ */
+declare function getErrorRetentionDays(): number;
+/**
+ * Get log retention days
+ */
+declare function getLogRetentionDays(): number;
+/**
+ * Get minimum status code for error tracking
+ */
+declare function getMinStatusCode(): number;
+
+export { type MonitorConfig, configureMonitor, env, getErrorRetentionDays, getLogRetentionDays, getMinStatusCode, getMonitorConfig, getSlackWebhookUrl, monitorEnvSchema };

package/dist/config/index.js

@@ -0,0 +1,72 @@
+// src/config/index.ts
+import { createEnvRegistry } from "@spfn/core/env";
+
+// src/config/schema.ts
+import { defineEnvSchema, envString, envNumber } from "@spfn/core/env";
+var monitorEnvSchema = defineEnvSchema({
+  SPFN_MONITOR_SLACK_WEBHOOK_URL: {
+    ...envString({
+      description: "Slack webhook URL for error notifications (falls back to notification default)",
+      required: false,
+      examples: ["https://hooks.slack.com/services/xxx/xxx/xxx"]
+    })
+  },
+  SPFN_MONITOR_ERROR_RETENTION_DAYS: {
+    ...envNumber({
+      description: "Number of days to retain error events before purging",
+      default: 90,
+      required: false,
+      examples: [30, 60, 90]
+    })
+  },
+  SPFN_MONITOR_LOG_RETENTION_DAYS: {
+    ...envNumber({
+      description: "Number of days to retain logs before purging",
+      default: 30,
+      required: false,
+      examples: [7, 14, 30]
+    })
+  },
+  SPFN_MONITOR_MIN_STATUS_CODE: {
+    ...envNumber({
+      description: "Minimum HTTP status code to track as error",
+      default: 500,
+      required: false,
+      examples: [400, 500]
+    })
+  }
+});
+
+// src/config/index.ts
+var registry = createEnvRegistry(monitorEnvSchema);
+var env = registry.validate();
+var globalConfig = {};
+function configureMonitor(config) {
+  globalConfig = { ...globalConfig, ...config };
+}
+function getMonitorConfig() {
+  return { ...globalConfig };
+}
+function getSlackWebhookUrl() {
+  return globalConfig.slackWebhookUrl || env.SPFN_MONITOR_SLACK_WEBHOOK_URL;
+}
+function getErrorRetentionDays() {
+  return globalConfig.errorRetentionDays ?? env.SPFN_MONITOR_ERROR_RETENTION_DAYS ?? 90;
+}
+function getLogRetentionDays() {
+  return globalConfig.logRetentionDays ?? env.SPFN_MONITOR_LOG_RETENTION_DAYS ?? 30;
+}
+function getMinStatusCode() {
+  return globalConfig.minStatusCode ?? env.SPFN_MONITOR_MIN_STATUS_CODE ?? 500;
+}
+export {
+  configureMonitor,
+  env,
+  getErrorRetentionDays,
+  getLogRetentionDays,
+  getMinStatusCode,
+  getMonitorConfig,
+  getSlackWebhookUrl,
+  monitorEnvSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/config/index.ts","../../src/config/schema.ts"],"sourcesContent":["/**\n * @spfn/monitor - Configuration\n */\n\nimport { createEnvRegistry } from '@spfn/core/env';\nimport { monitorEnvSchema } from './schema';\n\nexport { monitorEnvSchema };\n\n/**\n * Environment registry\n */\nconst registry = createEnvRegistry(monitorEnvSchema);\nexport const env = registry.validate();\n\n/**\n * Monitor configuration\n */\nexport interface MonitorConfig\n{\n    /**\n     * Slack webhook URL override\n     */\n    slackWebhookUrl?: string;\n\n    /**\n     * Error retention days\n     * @default 90\n     */\n    errorRetentionDays?: number;\n\n    /**\n     * Log retention days\n     * @default 30\n     */\n    logRetentionDays?: number;\n\n    /**\n     * Minimum HTTP status code to track\n     * @default 500\n     */\n    minStatusCode?: number;\n}\n\nlet globalConfig: MonitorConfig = {};\n\n/**\n * Configure monitor settings\n */\nexport function configureMonitor(config: MonitorConfig): void\n{\n    globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get current monitor configuration\n */\nexport function getMonitorConfig(): MonitorConfig\n{\n    return { ...globalConfig };\n}\n\n/**\n * Get Slack webhook URL (config > env)\n */\nexport function getSlackWebhookUrl(): string | undefined\n{\n    return globalConfig.slackWebhookUrl || env.SPFN_MONITOR_SLACK_WEBHOOK_URL;\n}\n\n/**\n * Get error retention days\n */\nexport function getErrorRetentionDays(): number\n{\n    return globalConfig.errorRetentionDays ?? env.SPFN_MONITOR_ERROR_RETENTION_DAYS ?? 90;\n}\n\n/**\n * Get log retention days\n */\nexport function getLogRetentionDays(): number\n{\n    return globalConfig.logRetentionDays ?? env.SPFN_MONITOR_LOG_RETENTION_DAYS ?? 30;\n}\n\n/**\n * Get minimum status code for error tracking\n */\nexport function getMinStatusCode(): number\n{\n    return globalConfig.minStatusCode ?? env.SPFN_MONITOR_MIN_STATUS_CODE ?? 500;\n}\n","/**\n * @spfn/monitor - Environment Schema\n */\n\nimport { defineEnvSchema, envString, envNumber } from '@spfn/core/env';\n\nexport const monitorEnvSchema = defineEnvSchema({\n    SPFN_MONITOR_SLACK_WEBHOOK_URL: {\n        ...envString({\n            description: 'Slack webhook URL for error notifications (falls back to notification default)',\n            required: false,\n            examples: ['https://hooks.slack.com/services/xxx/xxx/xxx'],\n        }),\n    },\n\n    SPFN_MONITOR_ERROR_RETENTION_DAYS: {\n        ...envNumber({\n            description: 'Number of days to retain error events before purging',\n            default: 90,\n            required: false,\n            examples: [30, 60, 90],\n        }),\n    },\n\n    SPFN_MONITOR_LOG_RETENTION_DAYS: {\n        ...envNumber({\n            description: 'Number of days to retain logs before purging',\n            default: 30,\n            required: false,\n            examples: [7, 14, 30],\n        }),\n    },\n\n    SPFN_MONITOR_MIN_STATUS_CODE: {\n        ...envNumber({\n            description: 'Minimum HTTP status code to track as error',\n            default: 500,\n            required: false,\n            examples: [400, 500],\n        }),\n    },\n});\n"],"mappings":";AAIA,SAAS,yBAAyB;;;ACAlC,SAAS,iBAAiB,WAAW,iBAAiB;AAE/C,IAAM,mBAAmB,gBAAgB;AAAA,EAC5C,gCAAgC;AAAA,IAC5B,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,UAAU;AAAA,MACV,UAAU,CAAC,8CAA8C;AAAA,IAC7D,CAAC;AAAA,EACL;AAAA,EAEA,mCAAmC;AAAA,IAC/B,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,SAAS;AAAA,MACT,UAAU;AAAA,MACV,UAAU,CAAC,IAAI,IAAI,EAAE;AAAA,IACzB,CAAC;AAAA,EACL;AAAA,EAEA,iCAAiC;AAAA,IAC7B,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,SAAS;AAAA,MACT,UAAU;AAAA,MACV,UAAU,CAAC,GAAG,IAAI,EAAE;AAAA,IACxB,CAAC;AAAA,EACL;AAAA,EAEA,8BAA8B;AAAA,IAC1B,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,SAAS;AAAA,MACT,UAAU;AAAA,MACV,UAAU,CAAC,KAAK,GAAG;AAAA,IACvB,CAAC;AAAA,EACL;AACJ,CAAC;;;AD7BD,IAAM,WAAW,kBAAkB,gBAAgB;AAC5C,IAAM,MAAM,SAAS,SAAS;AA+BrC,IAAI,eAA8B,CAAC;AAK5B,SAAS,iBAAiB,QACjC;AACI,iBAAe,EAAE,GAAG,cAAc,GAAG,OAAO;AAChD;AAKO,SAAS,mBAChB;AACI,SAAO,EAAE,GAAG,aAAa;AAC7B;AAKO,SAAS,qBAChB;AACI,SAAO,aAAa,mBAAmB,IAAI;AAC/C;AAKO,SAAS,wBAChB;AACI,SAAO,aAAa,sBAAsB,IAAI,qCAAqC;AACvF;AAKO,SAAS,sBAChB;AACI,SAAO,aAAa,oBAAoB,IAAI,mCAAmC;AACnF;AAKO,SAAS,mBAChB;AACI,SAAO,aAAa,iBAAiB,IAAI,gCAAgC;AAC7E;","names":[]}