@remote-logger/sdk 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# Remote Logger SDK
+
+A lightweight logging SDK that sends structured logs to a Remote Logger backend via HTTP or WebSocket, while echoing to the local console.
+
+## Quick Start
+
+```ts
+import { createLogger } from '@remote-logger/sdk';
+
+const logger = createLogger({
+  logId: 'your-log-file-id',
+  apiKey: 'your-api-key',
+});
+
+logger.info("server started", { port: 3000 });
+logger.warn("slow query", { duration: 1200, query: "SELECT ..." });
+logger.error("payment failed", { orderId: "abc-123" });
+```
+
+## Configuration
+
+```ts
+const logger = createLogger({
+  // Required
+  logId: 'uuid',             // Log file ID from the dashboard
+  apiKey: 'your-api-key',    // API key for ingestion auth
+
+  // Optional
+  group: 'api',              // Default group for all entries
+  traceId: 'req-123',        // Default trace ID
+  silent: false,             // Set true to suppress console output (default: false)
+  level: 'DEBUG',            // Only send logs at this level and above (default: 'DEBUG')
+  onError: (err, logs) => {  // Custom error handler for flush failures
+    // handle error
+  },
+});
+```
+
+### `level` option
+
+Controls which logs are sent to the remote service. Defaults to `'DEBUG'` (send everything). Logs below this level are silently dropped — they won't be sent remotely or printed to the console.
+
+This is useful when you want full remote logging in production but don't need to send every debug log during local development where you're already watching the console:
+
+```ts
+const logger = createLogger({
+  logId: 'your-log-file-id',
+  apiKey: 'your-api-key',
+  level: process.env.NODE_ENV === 'production' ? 'DEBUG' : 'ERROR',
+});
+```
+
+In this setup, local dev only sends errors remotely (you're already seeing everything in your terminal), while production captures the full picture for dashboard viewing and LLM analysis.
+
+### `silent` option
+
+By default, every `logger.*` call also prints to the local console so developers don't lose visibility when replacing `console.log` with `logger.info`. Set `silent: true` in production to disable this.
+
+## Log Methods
+
+Every level supports two call styles:
+
+### Simple form — message + optional metadata
+
+```ts
+logger.debug("cache miss", { key: "user:42" });
+logger.info("request handled", { method: "GET", path: "/api/users", ms: 12 });
+logger.warn("rate limit approaching", { current: 95, max: 100 });
+logger.error("query failed", { table: "orders" });
+logger.fatal("database unreachable");
+```
+
+The second argument is a plain metadata object. It can contain nested objects and arrays — the SDK sends it as-is.
+
+### Object form — for per-call group or trace ID
+
+```ts
+logger.info({
+  message: "user signed in",
+  group: "auth",
+  traceId: "req-abc",
+  metadata: { userId: 123, method: "oauth" },
+});
+```
+
+Use this when you need to override `group` or `traceId` on a single call without changing the logger's defaults.
+
+## Error Logging
+
+`error()` and `fatal()` accept Error objects directly — the SDK extracts the message, stack trace, and error type automatically:
+
+```ts
+try {
+  await processPayment(order);
+} catch (err) {
+  logger.error(err as Error, { orderId: order.id });
+}
+```
+
+This populates the `stack` and `error_type` columns in ClickHouse so stack traces and exception class names are stored as structured fields, not mashed into the message.
+
+## Scoped Loggers
+
+### Group Logger
+
+```ts
+const authLogger = logger.withGroup("auth");
+authLogger.info("login attempt", { email: "user@example.com" });
+// → group: "auth"
+```
+
+### Trace Logger
+
+```ts
+const reqLogger = logger.withTraceId("req-abc-123");
+reqLogger.info("handling request");
+reqLogger.warn("slow downstream call", { service: "billing", ms: 800 });
+// → trace_id: "req-abc-123" on both entries
+```
+
+### Mutating defaults
+
+```ts
+// Set for all subsequent calls
+logger.setGroup("worker");
+logger.setTraceId("job-456");
+
+// Clear
+logger.setGroup(undefined);
+logger.setTraceId(undefined);
+```
+
+## Console Interception
+
+Capture existing `console.*` calls without changing application code:
+
+```ts
+logger.interceptConsole();       // uses group "console"
+logger.interceptConsole("app");  // uses custom group
+
+// Later, to restore original console behavior:
+logger.restoreConsole();
+```
+
+This wraps `console.debug`, `console.log`, `console.info`, and `console.warn`. Errors are captured via `window.addEventListener('error')` and `unhandledrejection` listeners instead of wrapping `console.error`, to avoid polluting stack traces in frameworks like Next.js/React.
+
+## AI Assistant Integration
+
+Run the init command to configure your AI coding assistant (Claude Code, Cursor, etc.) to use the SDK:
+
+```bash
+npx @remote-logger/sdk init
+```
+
+This adds a reference to the SDK's workflow guide in your `CLAUDE.md` and `.cursorrules`. Once configured, your AI assistant will know how to place logs using the SDK and query them via MCP — no copy-pasting logs needed.
+
+To set up manually, add this line to your `CLAUDE.md`:
+
+```md
+> See node_modules/@remote-logger/sdk/SKILL.md for the @remote-logger/sdk logging workflow.
+```
+
+## MCP Server (AI Log Analysis)
+
+Remote Logger includes an MCP server that lets AI assistants query your logs directly.
+
+### Add
+
+```bash
+claude mcp add remote-logger https://log.terodato.com/mcp --header "Authorization: Bearer YOUR_API_KEY"
+```
+
+### Remove
+
+```bash
+claude mcp remove remote-logger
+```

package/SKILL.md

@@ -0,0 +1,121 @@
+# @remote-logger/sdk — AI Workflow Guide
+
+This project uses Remote Logger to give you persistent runtime insight. You can place log statements freely — they are sent to a central server and you can query them via MCP at any time. This means you don't need to ask the user to copy-paste logs. You place them, the user reproduces the issue, and you query the results yourself.
+
+## The Workflow
+
+1. **Place logs** in the code using the SDK (see API below)
+2. **Ask the user to reproduce** the issue (or wait for the next occurrence)
+3. **Query the logs via MCP** using `logs_query` — you have direct access, no copy-pasting needed
+4. **Analyze and fix** based on the runtime data
+5. **Repeat** — leave useful logs in place, add more if needed
+
+You should default to placing logs early when investigating runtime issues. Don't spend multiple rounds guessing from static code alone — instrument the code, get the data, then fix the bug. Logs persist across runs, so once placed, they keep providing insight.
+
+**Cleanup rule:** Use `logger.debug()` for temporary diagnostic logs placed during investigation. Once the issue is resolved, remove all debug-level logs you added. Permanent logs that provide ongoing operational value (errors, warnings, key events) should use the appropriate level and can stay.
+
+## When to Place Logs
+
+- Debugging a runtime bug that isn't obvious from code alone
+- Investigating timing issues, race conditions, or intermittent failures
+- Understanding the flow through async code, event handlers, or callbacks
+- Correlating behavior across multiple services or processes (use `traceId`)
+- Monitoring a specific code path after a fix to verify it works
+
+## SDK Quick Reference
+
+### Setup (already done if the project uses this SDK)
+
+```ts
+import { createLogger } from '@remote-logger/sdk';
+
+const logger = createLogger({
+  logId: 'uuid-from-dashboard',   // required — identifies the log stream
+  apiKey: 'rl_...',               // required — ingestion auth
+  group: 'api',                   // optional: default group for all entries
+  traceId: 'req-123',            // optional: default trace ID
+  level: 'DEBUG',                 // optional: minimum level (default: 'DEBUG')
+  silent: false,                  // optional: suppress console echo (default: false)
+});
+```
+
+### Logging
+
+```ts
+logger.debug("cache hit", { key: "user:42" });
+logger.info("request handled", { method: "GET", path: "/api/users", ms: 12 });
+logger.warn("slow query", { duration: 1200 });
+logger.error(err as Error, { orderId: order.id });  // Error objects extract stack + error_type
+logger.fatal(new Error("database unreachable"));
+```
+
+### Scoped Loggers (for grouping or tracing)
+
+```ts
+const authLogger = logger.withGroup("auth");       // all calls get group: "auth"
+const reqLogger = logger.withTraceId("req-abc");    // all calls get trace_id: "req-abc"
+```
+
+Use `group` to categorize logs by subsystem (e.g., "auth", "billing", "renderer"). Use `traceId` to correlate logs across a single request or operation, especially across services.
+
+### Console Interception
+
+```ts
+logger.interceptConsole();        // captures console.debug/log/info/warn + unhandled errors
+logger.interceptConsole("app");   // with a custom group name
+logger.restoreConsole();          // undo
+```
+
+Use this to capture logs from third-party code or existing console.log statements without modifying them.
+
+## Reading Logs via MCP
+
+You have two MCP tools available:
+
+- **`logs_list_log_files`** — Lists all log files with data. Call this first to find the log file ID.
+- **`logs_query`** — Execute SQL (ClickHouse) against a log file. Tenant/log filtering is automatic.
+
+### Common Queries
+
+```sql
+-- Recent errors
+SELECT timestamp, level, message, stack FROM logs.entries WHERE level = 'ERROR' ORDER BY timestamp DESC LIMIT 20
+
+-- Errors by type
+SELECT error_type, count(*) as cnt FROM logs.entries WHERE error_type IS NOT NULL GROUP BY error_type ORDER BY cnt DESC
+
+-- Search for a specific message pattern
+SELECT timestamp, level, group, message FROM logs.entries WHERE message LIKE '%ECONNREFUSED%' ORDER BY timestamp DESC LIMIT 20
+
+-- Error rate over time
+SELECT toStartOfMinute(timestamp) as minute, count(*) FROM logs.entries WHERE level = 'ERROR' GROUP BY minute ORDER BY minute
+
+-- Logs by group
+SELECT group, count(*) FROM logs.entries GROUP BY group ORDER BY count() DESC
+
+-- Trace a specific request across services
+SELECT timestamp, group, level, message FROM logs.entries WHERE trace_id = 'req-abc-123' ORDER BY timestamp
+
+-- Recent logs from a specific group
+SELECT timestamp, level, message FROM logs.entries WHERE group = 'auth' ORDER BY timestamp DESC LIMIT 50
+```
+
+### Table Schema
+
+```
+seq UInt64              -- sequence number
+timestamp DateTime64(3) -- e.g., '2025-01-22 14:30:00.123'
+level String            -- DEBUG, INFO, WARN, ERROR, FATAL
+trace_id String         -- request correlation
+group String            -- categorization (e.g., 'api/billing', 'main', 'renderer')
+message String          -- log content
+stack Nullable(String)  -- stack trace
+error_type String       -- exception class name
+metadata Map(String, String) -- arbitrary key-value pairs
+```
+
+## Do NOT
+
+- Do not pass `batchSize`, `flushInterval`, `httpEndpoint`, `wsEndpoint`, or `transport` — these do not exist.
+- Do not call `errorWithStack()` — it does not exist. Use `logger.error(err)` instead.
+- Do not call `logger.shutdown()` unless explicitly tearing down the logger mid-process. It is not required.

package/dist/index.d.mts

@@ -0,0 +1,130 @@
+type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+interface LoggerConfig {
+    logId: string;
+    apiKey?: string;
+    group?: string;
+    /** Only send logs at this level and above to the remote service (default: 'DEBUG' — sends everything) */
+    level?: LogLevel;
+    onError?: (error: Error, logs: InternalLogEntry[]) => void;
+    traceId?: string;
+    /** When true, skip console output from logger.* methods; default false */
+    silent?: boolean;
+    /** When true, log SDK internal operations to console for troubleshooting */
+    debug?: boolean;
+    /** @internal Override base URL for development (e.g. 'http://localhost:3500') */
+    _endpoint?: string;
+    /** @internal Override WebSocket base URL for development (e.g. 'ws://localhost:3501') */
+    _wsEndpoint?: string;
+    /** @internal Full URL for log ingestion proxy (e.g. '/api/internal/ingest'). When set, uses this as the POST URL directly (no /ingest/http appended), skips WebSocket. */
+    _ingestUrl?: string;
+}
+interface InternalLogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    logId: string;
+    group?: string;
+    trace_id?: string;
+    stack?: string;
+    error_type?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Object form for logger.info({ message, group?, metadata? }) */
+interface LogEntryObject {
+    message: string;
+    group?: string;
+    traceId?: string;
+    metadata?: Record<string, unknown>;
+}
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'failed';
+declare class Logger {
+    private config;
+    private baseUrl;
+    private httpIngestUrl;
+    private wsIngestUrl;
+    private proxyMode;
+    private buffer;
+    private flushTimer;
+    private flushPromise;
+    private consoleIntercepted;
+    private httpBackoffMs;
+    private maxBackoffMs;
+    private consecutiveHttpFailures;
+    private _onError;
+    private _onUnhandledRejection;
+    private ws;
+    private wsState;
+    private wsReconnectTimer;
+    private wsReconnectAttempts;
+    private maxWsReconnectAttempts;
+    private _onVisibilityChange;
+    private _onBeforeUnload;
+    constructor(config: LoggerConfig);
+    private debugLog;
+    private connectWebSocket;
+    private startFlushTimer;
+    private shouldLog;
+    private formatArgs;
+    private static readonly CONSOLE_METHOD;
+    private log;
+    private parseArgs;
+    debug(entry: LogEntryObject): void;
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(entry: LogEntryObject): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(entry: LogEntryObject): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(entry: LogEntryObject): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    error(err: Error, metadata?: Record<string, unknown>): void;
+    fatal(entry: LogEntryObject): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+    fatal(err: Error, metadata?: Record<string, unknown>): void;
+    withTraceId(traceId: string): TraceLogger;
+    withGroup(group: string): GroupLogger;
+    setTraceId(traceId: string | undefined): void;
+    setGroup(group: string | undefined): void;
+    interceptConsole(group?: string): void;
+    restoreConsole(): void;
+    flush(): Promise<void>;
+    private doFlush;
+    private sendViaWebSocket;
+    private sendViaHttp;
+    /** Fire-and-forget flush using fetch with keepalive (works during page unload) */
+    private flushSync;
+    private registerLifecycleHooks;
+    /** Check server connectivity and API key validity */
+    ping(): Promise<{
+        ok: boolean;
+        latencyMs: number;
+        error?: string;
+    }>;
+    /** Get current connection status */
+    getConnectionStatus(): {
+        transport: 'websocket' | 'http';
+        state: ConnectionState;
+    };
+}
+declare class TraceLogger {
+    private parent;
+    private traceId;
+    constructor(parent: Logger, traceId: string);
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+}
+declare class GroupLogger {
+    private parent;
+    private group;
+    constructor(parent: Logger, group: string);
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+}
+declare function createLogger(config: LoggerConfig): Logger;
+
+export { type InternalLogEntry, type LogEntryObject, type LogLevel, Logger, type LoggerConfig, createLogger, createLogger as default };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+type LogLevel = 'DEBUG' | 'INFO' | 'WARN' | 'ERROR' | 'FATAL';
+interface LoggerConfig {
+    logId: string;
+    apiKey?: string;
+    group?: string;
+    /** Only send logs at this level and above to the remote service (default: 'DEBUG' — sends everything) */
+    level?: LogLevel;
+    onError?: (error: Error, logs: InternalLogEntry[]) => void;
+    traceId?: string;
+    /** When true, skip console output from logger.* methods; default false */
+    silent?: boolean;
+    /** When true, log SDK internal operations to console for troubleshooting */
+    debug?: boolean;
+    /** @internal Override base URL for development (e.g. 'http://localhost:3500') */
+    _endpoint?: string;
+    /** @internal Override WebSocket base URL for development (e.g. 'ws://localhost:3501') */
+    _wsEndpoint?: string;
+    /** @internal Full URL for log ingestion proxy (e.g. '/api/internal/ingest'). When set, uses this as the POST URL directly (no /ingest/http appended), skips WebSocket. */
+    _ingestUrl?: string;
+}
+interface InternalLogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    logId: string;
+    group?: string;
+    trace_id?: string;
+    stack?: string;
+    error_type?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Object form for logger.info({ message, group?, metadata? }) */
+interface LogEntryObject {
+    message: string;
+    group?: string;
+    traceId?: string;
+    metadata?: Record<string, unknown>;
+}
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'failed';
+declare class Logger {
+    private config;
+    private baseUrl;
+    private httpIngestUrl;
+    private wsIngestUrl;
+    private proxyMode;
+    private buffer;
+    private flushTimer;
+    private flushPromise;
+    private consoleIntercepted;
+    private httpBackoffMs;
+    private maxBackoffMs;
+    private consecutiveHttpFailures;
+    private _onError;
+    private _onUnhandledRejection;
+    private ws;
+    private wsState;
+    private wsReconnectTimer;
+    private wsReconnectAttempts;
+    private maxWsReconnectAttempts;
+    private _onVisibilityChange;
+    private _onBeforeUnload;
+    constructor(config: LoggerConfig);
+    private debugLog;
+    private connectWebSocket;
+    private startFlushTimer;
+    private shouldLog;
+    private formatArgs;
+    private static readonly CONSOLE_METHOD;
+    private log;
+    private parseArgs;
+    debug(entry: LogEntryObject): void;
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(entry: LogEntryObject): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(entry: LogEntryObject): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(entry: LogEntryObject): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    error(err: Error, metadata?: Record<string, unknown>): void;
+    fatal(entry: LogEntryObject): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+    fatal(err: Error, metadata?: Record<string, unknown>): void;
+    withTraceId(traceId: string): TraceLogger;
+    withGroup(group: string): GroupLogger;
+    setTraceId(traceId: string | undefined): void;
+    setGroup(group: string | undefined): void;
+    interceptConsole(group?: string): void;
+    restoreConsole(): void;
+    flush(): Promise<void>;
+    private doFlush;
+    private sendViaWebSocket;
+    private sendViaHttp;
+    /** Fire-and-forget flush using fetch with keepalive (works during page unload) */
+    private flushSync;
+    private registerLifecycleHooks;
+    /** Check server connectivity and API key validity */
+    ping(): Promise<{
+        ok: boolean;
+        latencyMs: number;
+        error?: string;
+    }>;
+    /** Get current connection status */
+    getConnectionStatus(): {
+        transport: 'websocket' | 'http';
+        state: ConnectionState;
+    };
+}
+declare class TraceLogger {
+    private parent;
+    private traceId;
+    constructor(parent: Logger, traceId: string);
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+}
+declare class GroupLogger {
+    private parent;
+    private group;
+    constructor(parent: Logger, group: string);
+    debug(message: string, metadata?: Record<string, unknown>): void;
+    info(message: string, metadata?: Record<string, unknown>): void;
+    warn(message: string, metadata?: Record<string, unknown>): void;
+    error(message: string, metadata?: Record<string, unknown>): void;
+    fatal(message: string, metadata?: Record<string, unknown>): void;
+}
+declare function createLogger(config: LoggerConfig): Logger;
+
+export { type InternalLogEntry, type LogEntryObject, type LogLevel, Logger, type LoggerConfig, createLogger, createLogger as default };