@hardlydifficult/logger 1.0.11 → 1.0.12

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/logger
 
-Plugin-based structured logger with configurable log levels and extensible output handlers for Console, File, and Discord.
+Plugin-based structured logger with configurable log levels and extensible output handlers for Console, File, Discord, and Session-based JSONL tracking.
 
 ## Installation
 
@@ -60,6 +60,15 @@ logger.debug("This goes to console only");
 logger.error("This goes to both console and file");
 ```
 
+### Notifications
+
+Out-of-band notifications are sent to plugins that implement `notify()`.
+
+```typescript
+logger.notify("Deployment complete");
+// DiscordPlugin will send this as a standalone message; other plugins ignore it.
+```
+
 ## Console Plugin
 
 Outputs formatted log entries to the console, routing to `console.log`, `console.warn`, or `console.error` based on log level.
@@ -106,39 +115,130 @@ logger.info("Request processed", { method: "GET", path: "/api/users" });
 
 ## Discord Plugin
 
-Forwards warn/error log entries and notifications to Discord via a configurable sender function. Useful for alerting on critical issues.
+Forwards `warn` and `error` log entries and notifications to Discord via a configurable sender function. Useful for alerting on critical issues.
+
+### Setup
+
+1. Create a Discord webhook for your channel.
+2. Configure the sender to POST to the webhook URL.
 
 ```typescript
 import { Logger, DiscordPlugin } from "@hardlydifficult/logger";
 
+const logger = new Logger("warn");
 const discord = new DiscordPlugin();
-const logger = new Logger("info").use(discord);
 
-// Set the sender once your Discord bot is ready
-discord.setSender((msg) => channel.send(msg));
+discord.setSender((message) => {
+  // Example: use node:fetch or your preferred HTTP client
+  // fetch("https://discord.com/api/webhooks/...", {
+  //   method: "POST",
+  //   headers: { "Content-Type": "application/json" },
+  //   body: JSON.stringify({ content: message })
+  // });
+});
 
-logger.warn("High memory usage", { usage: "85%" });
-// Sends to Discord: ⚠️ **WARN**: High memory usage
-// ```json
-// {
-//   "usage": "85%"
-// }
-// ```
-
-logger.notify("Deployment complete");
-// Sends to Discord: Deployment complete
+logger.use(discord);
 ```
 
 ### Behavior
 
 | Behavior | Description |
-|----------|-------------|
+|--------|-------------|
 | Only `warn` and `error` log entries are sent (debug/info are filtered) | |
 | Warn entries use ⚠️ emoji; error entries use 🚨 emoji | |
 | Context is formatted as a JSON code block when present | |
 | `notify()` sends messages directly without level filtering | |
 | If `setSender` is not called, entries are silently dropped | |
 
+### Formatting
+
+Error entries include a siren emoji and JSON context in a code block; warnings use a warning emoji.
+
+```typescript
+logger.error("Database unavailable", { host: "db.example.com", retry: 3 });
+// ➡️ Sends to Discord:
+// 🚨 **ERROR**: Database unavailable
+// ```json
+// {
+//   "host": "db.example.com",
+//   "retry": 3
+// }
+// ```
+
+logger.warn("Slow query detected", { durationMs: 2500 });
+// ➡️ Sends to Discord:
+// ⚠️ **WARN**: Slow query detected
+```
+
+## Session Tracking
+
+The `SessionTracker` class persists structured session logs as JSONL files for debugging and analysis.
+
+### SessionTracker
+
+Create a tracker pointing to a writable state directory.
+
+```typescript
+import { SessionTracker } from "@hardlydifficult/logger";
+
+const tracker = new SessionTracker({
+  stateDirectory: "/var/log", // Required
+  subdirectory: "ai-sessions", // Optional, defaults to "sessions"
+  maxAgeMs: 7 * 24 * 60 * 60 * 1000, // Optional, defaults to 7 days
+});
+```
+
+### Append Entries
+
+Each entry includes a type discriminator and arbitrary data.
+
+```typescript
+tracker.append("sess-abc123", {
+  type: "session_start",
+  data: { userId: 456, prompt: "Hello" },
+});
+
+tracker.append("sess-abc123", {
+  type: "ai_response",
+  data: { response: "Hi there!", model: "gpt-4" },
+});
+
+tracker.append("sess-abc123", {
+  type: "tool_call",
+  data: { name: "Search", input: { query: "weather" } },
+});
+```
+
+### Read & List Sessions
+
+```typescript
+// Read all entries for a session
+const entries = tracker.read("sess-abc123");
+// Returns SessionEntry[] in chronological order
+
+// List all tracked sessions with metadata
+const sessions = tracker.list();
+// Returns SessionInfo[] sorted by lastModifiedAt descending
+```
+
+### Session Metadata
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId` | string | Name of the `.jsonl` file (without extension) |
+| `sizeBytes` | number | File size on disk |
+| `startedAt` | string | ISO timestamp (first entry or file creation time) |
+| `lastModifiedAt` | string | ISO timestamp of file’s last write |
+| `entryCount` | number | Number of JSONL lines in the file |
+
+### Session Operations
+
+```typescript
+tracker.has("sess-abc123"); // true/false
+tracker.delete("sess-abc123"); // true if deleted, false if missing
+tracker.cleanup(); // Deletes files older than maxAgeMs, returns count deleted
+```
+
 ## Custom Plugins
 
 Implement the `LoggerPlugin` interface to create custom output handlers:
@@ -165,20 +265,28 @@ const logger = new Logger("info").use(new SlackPlugin());
 ## Types
 
 ```typescript
-type LogLevel = "debug" | "info" | "warn" | "error";
-
-interface LogEntry {
-  readonly level: LogLevel;
-  readonly message: string;
-  readonly timestamp: string; // ISO 8601 format
-  readonly context?: Readonly<Record<string, unknown>>;
-}
+import type {
+  LogLevel,
+  LogEntry,
+  LoggerPlugin,
+  SessionEntry,
+  SessionEntryType,
+  SessionInfo,
+  SessionTrackerOptions,
+} from "@hardlydifficult/logger";
+```
 
-interface LoggerPlugin {
-  log(entry: LogEntry): void;
-  notify?(message: string): void;
-}
+| Type | Description |
+|------|-------------|
+| `LogLevel` | `"debug" \| "info" \| "warn" \| "error"` |
+| `LogEntry` | `{ level, message, timestamp, context? }` |
+| `LoggerPlugin` | `{ log(entry): void; notify?(message): void }` |
+| `SessionEntryType` | `"session_start" \| "ai_request" \| "ai_response" \| "tool_call" \| "tool_result" \| "error" \| "session_end" \| "metadata"` |
+| `SessionEntry` | `{ type, timestamp, data }` |
+| `SessionInfo` | Metadata about persisted session files |
+| `SessionTrackerOptions` | `stateDirectory` (required), `subdirectory?`, `maxAgeMs?` |
 
+```typescript
 type DiscordSender = (message: string) => void;
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/logger",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [