loglyn 0.0.1

package/README.md

@@ -0,0 +1,163 @@
+# loglyn
+
+Production runtime logs for NestJS with an embedded dashboard.
+
+## Install
+
+```bash
+npm install loglyn
+```
+
+## Setup
+
+Register the module:
+
+```ts
+import { Module } from '@nestjs/common';
+import { NestLogsModule } from 'loglyn';
+
+@Module({
+  imports: [
+    NestLogsModule.register({
+      timezone: 'Asia/Jakarta',
+      path: '/nest-logs',
+      title: 'Production Logs',
+      maxLogs: 1000,
+      storagePath: './logs',
+      retentionDays: 30,
+      password: process.env.NEST_LOGS_PASSWORD,
+      captureRequests: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Use it as the Nest logger:
+
+```ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import { NestLogsLogger } from 'loglyn';
+
+const bootstrap = async () => {
+  const app = await NestFactory.create(AppModule, { bufferLogs: true });
+  app.useLogger(app.get(NestLogsLogger));
+  await app.listen(process.env.PORT ?? 3000);
+};
+
+void bootstrap();
+```
+
+Open `http://localhost:3000/nest-logs`.
+
+## Options
+
+```ts
+NestLogsModule.register({
+  timezone: 'Asia/Jakarta',
+  path: '/nest-logs',
+  title: 'Production Logs',
+  maxLogs: 1000,
+  storagePath: './logs',
+  retentionDays: 30,
+  password: process.env.NEST_LOGS_PASSWORD,
+  sessionTtlMs: 1000 * 60 * 60 * 8,
+  captureRequests: true,
+  captureRequestBody: false,
+  captureResponseBody: false,
+  maxBodySize: 4096,
+  redact: ['authorization', 'cookie', 'set-cookie', 'password', 'token'],
+})
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `timezone` | `string` | required | Timezone for daily log filenames and retention. Example: `Asia/Jakarta`. |
+| `path` | `string` | `/nest-logs` | Dashboard and API base path. Example: `/logs` opens the dashboard at `http://localhost:3000/logs`. |
+| `title` | `string` | `loglyn` | Dashboard and browser tab title. |
+| `maxLogs` | `number` | `1000` | Maximum in-memory logs kept for realtime dashboard history. Older logs are removed from memory first. |
+| `storagePath` | `string` | none | Folder for daily `.jsonl` files. Example: `./logs` writes `logs/YYYY-MM-DD.jsonl`. Leave empty to disable file storage. |
+| `retentionDays` | `number` | none | How many days of `.jsonl` files to keep when `storagePath` is enabled. Leave empty to never delete log files automatically. |
+| `password` | `string` | none | Optional dashboard password. Users see a password screen before opening logs. |
+| `token` | `string` | none | Optional dashboard/API access token. Leave empty only for local development. |
+| `sessionTtlMs` | `number` | 8 hours | Dashboard session token lifetime after login. |
+| `captureRequests` | `boolean` | `false` | Capture HTTP requests automatically without manual `Logger` calls. |
+| `captureRequestBody` | `boolean` | `false` | Capture parsed request body. Keep disabled unless needed because bodies can contain secrets. |
+| `captureResponseBody` | `boolean` | `false` | Reserved for response body capture. Disabled by default. |
+| `maxBodySize` | `number` | `4096` | Maximum serialized size for captured request data before truncation. |
+| `redact` | `string[]` | sensitive defaults | Extra keys to hide from headers, query, and body. Case-insensitive. |
+
+If `storagePath` is set, logs are appended as daily JSONL files.
+
+When the app starts, today's JSONL file is loaded back into the in-memory buffer, then realtime logs are merged into the same dashboard stream.
+
+## Capture HTTP Requests
+
+Enable request monitoring:
+
+```ts
+NestLogsModule.register({
+  timezone: 'Asia/Jakarta',
+  path: '/logs',
+  password: process.env.NEST_LOGS_PASSWORD,
+  storagePath: './logs',
+  captureRequests: true,
+})
+```
+
+Captured request rows include:
+
+- method and path
+- status code
+- duration
+- IP
+- user-agent
+- request headers
+- response headers
+- query
+- request body only when `captureRequestBody` is `true`
+- response body only when `captureResponseBody` is `true`
+
+Dashboard routes are skipped automatically, so `/logs/*` will not spam itself.
+
+Date range filters fetch historical JSONL files from disk, then merge them with the realtime buffer.
+
+Default redacted keys:
+
+```ts
+['authorization', 'cookie', 'set-cookie', 'password', 'token', 'secret', 'api-key', 'x-api-key']
+```
+
+For production, keep body capture disabled unless you have a clear debugging need.
+
+## API
+
+- `GET /nest-logs`
+- `GET /nest-logs/api/logs`
+- `GET /nest-logs/api/dates`
+- `GET /nest-logs/api/stream`
+
+Filters for `/api/logs`:
+
+- `level`
+- `search`
+- `from`
+- `to`
+- `date`
+
+## Security
+
+Set `password` before exposing this dashboard outside local development.
+
+Dashboard users enter the password in the browser. The dashboard exchanges it for a temporary session token and stores that token in `sessionStorage`.
+
+```http
+Authorization: Bearer <session-token>
+```
+
+If the token expires or becomes invalid, the dashboard shows the login screen again.
+
+## License
+
+MIT