@remote-logger/sdk 0.1.4 → 0.1.6

package/README.md

@@ -144,6 +144,33 @@ 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.
 
+## Source Map Support (Vite)
+
+Automatically resolve minified production stack traces back to original source. The Vite plugin uploads source maps at build time, and the ingestion service resolves stack traces before storing them.
+
+```ts
+// vite.config.ts
+import remoteLoggerPlugin from '@remote-logger/sdk/vite';
+
+export default defineConfig({
+  plugins: [
+    remoteLoggerPlugin({
+      apiKey: process.env.REMOTE_LOGGER_API_KEY!,
+      logFileId: 'your-log-file-id',
+    }),
+  ],
+  build: { sourcemap: true },
+});
+```
+
+The plugin:
+- **Skips in dev mode** — stacks are already readable
+- **Generates a release UUID** per build, injected as `__REMOTE_LOGGER_RELEASE__`
+- **Uploads `.map` files** from the build output to the ingestion service on `closeBundle`
+- **Multi-bundle (Electron):** All plugin instances in the same Node process share one release ID, so main + renderer maps are grouped under the same release
+
+No SDK configuration needed — the SDK automatically detects `__REMOTE_LOGGER_RELEASE__` and attaches it to every log entry.
+
 ## AI Assistant Integration
 
 Run the init command to configure your AI coding assistant (Claude Code, Cursor, etc.) to use the SDK:

package/SKILL.md

@@ -22,10 +22,34 @@ You should default to placing logs early when investigating runtime issues. Don'
 - Correlating behavior across multiple services or processes (use `traceId`)
 - Monitoring a specific code path after a fix to verify it works
 
+## Best Practices
+
+**Use `withGroup()` to categorize logs — don't embed context in the message.**
+
+The `group` field is a queryable column in ClickHouse. When you prefix messages manually, you lose the ability to filter and aggregate by subsystem.
+
+```ts
+// Bad — context is buried in the message string, not queryable
+logger.info("[StorageService] Getting user");
+
+// Good — group is a structured, queryable field
+const log = logger.withGroup("StorageService");
+log.info("Getting user");
+
+// Also good — inline object form for one-off logs
+logger.info({ message: "Getting user", group: "StorageService" });
+```
+
+This lets you later query `WHERE group = 'StorageService'` or `GROUP BY group` to see log volume by subsystem.
+
+When placing logs across multiple files or modules during an investigation, create a scoped logger per module so logs are naturally organized. Use `withTraceId()` to correlate logs across a single request or operation, especially across services.
+
 ## SDK Quick Reference
 
 ### Setup (already done if the project uses this SDK)
 
+**Important:** Look for an existing logger instance in the project before creating a new one. Projects typically have a shared logger in a file like `logger.ts` or `lib/logger.ts` — import from there instead of calling `createLogger()` again.
+
 ```ts
 import { createLogger } from '@remote-logger/sdk';
 
@@ -49,15 +73,6 @@ logger.error(err as Error, { orderId: order.id });  // Error objects extract sta
 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
@@ -109,9 +124,10 @@ 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
+stack Nullable(String)  -- stack trace (resolved via source maps if available)
 error_type String       -- exception class name
-metadata Map(String, String) -- arbitrary key-value pairs
+release_id String       -- build release ID (for source map resolution)
+metadata JSON              -- arbitrary structured data
 ```
 
 ## Do NOT

package/dist/chunk-JKIIIVNW.mjs

@@ -0,0 +1,11 @@
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+export {
+  __privateAdd,
+  __privateMethod
+};

package/dist/index.d.mts

@@ -27,6 +27,7 @@ interface InternalLogEntry {
     trace_id?: string;
     stack?: string;
     error_type?: string;
+    release_id?: string;
     metadata?: Record<string, unknown>;
 }
 /** Object form for logger.info({ message, group?, metadata? }) */

package/dist/index.d.ts

@@ -27,6 +27,7 @@ interface InternalLogEntry {
     trace_id?: string;
     stack?: string;
     error_type?: string;
+    release_id?: string;
     metadata?: Record<string, unknown>;
 }
 /** Object form for logger.info({ message, group?, metadata? }) */

package/dist/index.js

@@ -339,6 +339,7 @@ function isErrorLike(value) {
 }
 
 // src/index.ts
+var RELEASE_ID = typeof __REMOTE_LOGGER_RELEASE__ !== "undefined" ? __REMOTE_LOGGER_RELEASE__ : void 0;
 var LEVEL_ORDER = {
   DEBUG: 0,
   INFO: 1,
@@ -519,6 +520,7 @@ ${arg.stack}`;
       trace_id: options?.traceId ?? this.config.traceId,
       stack: options?.stack,
       error_type: options?.errorType,
+      release_id: RELEASE_ID,
       metadata: options?.metadata
     };
     this.buffer.push(entry);

package/dist/index.mjs

@@ -1,9 +1,7 @@
-var __typeError = (msg) => {
-  throw TypeError(msg);
-};
-var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
-var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+import {
+  __privateAdd,
+  __privateMethod
+} from "./chunk-JKIIIVNW.mjs";
 
 // ../node_modules/non-error/index.js
 var isNonErrorSymbol = /* @__PURE__ */ Symbol("isNonError");
@@ -312,6 +310,7 @@ function isErrorLike(value) {
 }
 
 // src/index.ts
+var RELEASE_ID = typeof __REMOTE_LOGGER_RELEASE__ !== "undefined" ? __REMOTE_LOGGER_RELEASE__ : void 0;
 var LEVEL_ORDER = {
   DEBUG: 0,
   INFO: 1,
@@ -492,6 +491,7 @@ ${arg.stack}`;
       trace_id: options?.traceId ?? this.config.traceId,
       stack: options?.stack,
       error_type: options?.errorType,
+      release_id: RELEASE_ID,
       metadata: options?.metadata
     };
     this.buffer.push(entry);

package/dist/vite.d.mts

@@ -0,0 +1,11 @@
+import { Plugin } from 'vite';
+
+interface RemoteLoggerPluginOptions {
+    apiKey: string;
+    logFileId: string;
+    /** @internal Override endpoint for development */
+    _endpoint?: string;
+}
+declare function remoteLoggerPlugin(options: RemoteLoggerPluginOptions): Plugin;
+
+export { type RemoteLoggerPluginOptions, remoteLoggerPlugin as default };

package/dist/vite.d.ts

@@ -0,0 +1,11 @@
+import { Plugin } from 'vite';
+
+interface RemoteLoggerPluginOptions {
+    apiKey: string;
+    logFileId: string;
+    /** @internal Override endpoint for development */
+    _endpoint?: string;
+}
+declare function remoteLoggerPlugin(options: RemoteLoggerPluginOptions): Plugin;
+
+export { type RemoteLoggerPluginOptions, remoteLoggerPlugin as default };

package/dist/vite.js

@@ -0,0 +1,109 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/vite.ts
+var vite_exports = {};
+__export(vite_exports, {
+  default: () => remoteLoggerPlugin
+});
+module.exports = __toCommonJS(vite_exports);
+var import_crypto = require("crypto");
+var import_fs = require("fs");
+var import_path = require("path");
+var DEFAULT_ENDPOINT = "https://log.terodato.com";
+function collectMapFiles(dir) {
+  const results = [];
+  try {
+    const entries = (0, import_fs.readdirSync)(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = (0, import_path.join)(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...collectMapFiles(fullPath));
+      } else if (entry.name.endsWith(".map")) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+var sharedReleaseId = null;
+function remoteLoggerPlugin(options) {
+  if (!sharedReleaseId) sharedReleaseId = (0, import_crypto.randomUUID)();
+  const releaseId = sharedReleaseId;
+  let resolvedConfig;
+  let skip = false;
+  return {
+    name: "remote-logger-sourcemap",
+    enforce: "post",
+    config(config, { command, mode }) {
+      if (mode === "development" || command === "serve") {
+        skip = true;
+        return;
+      }
+      return {
+        define: {
+          __REMOTE_LOGGER_RELEASE__: JSON.stringify(releaseId)
+        }
+      };
+    },
+    configResolved(config) {
+      resolvedConfig = config;
+    },
+    async closeBundle() {
+      if (skip) return;
+      const outDir = resolvedConfig.build.outDir;
+      const mapFiles = collectMapFiles(outDir);
+      if (mapFiles.length === 0) {
+        console.log("[RemoteLogger] No source map files found, skipping upload");
+        return;
+      }
+      const endpoint = options._endpoint || DEFAULT_ENDPOINT;
+      const url = `${endpoint}/sourcemaps/upload`;
+      const formData = new FormData();
+      formData.append("releaseId", releaseId);
+      formData.append("logFileId", options.logFileId);
+      for (const mapFile of mapFiles) {
+        const content = (0, import_fs.readFileSync)(mapFile);
+        const name = (0, import_path.relative)(outDir, mapFile).replace(/\\/g, "/").replace(/\//g, "_");
+        const blob = new Blob([content], { type: "application/json" });
+        formData.append("files", blob, name.endsWith(".map") ? name : `${name}.map`);
+      }
+      try {
+        console.log(`[RemoteLogger] Uploading ${mapFiles.length} source maps (release: ${releaseId})...`);
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${options.apiKey}`
+          },
+          body: formData
+        });
+        if (!response.ok) {
+          const body = await response.text();
+          console.error(`[RemoteLogger] Source map upload failed (${response.status}): ${body}`);
+          return;
+        }
+        const result = await response.json();
+        console.log(`[RemoteLogger] Uploaded ${result.count} source maps successfully`);
+      } catch (err) {
+        console.error("[RemoteLogger] Source map upload failed:", err);
+      }
+    }
+  };
+}

package/dist/vite.mjs

@@ -0,0 +1,90 @@
+import "./chunk-JKIIIVNW.mjs";
+
+// src/vite.ts
+import { randomUUID } from "crypto";
+import { readdirSync, readFileSync } from "fs";
+import { join, relative } from "path";
+var DEFAULT_ENDPOINT = "https://log.terodato.com";
+function collectMapFiles(dir) {
+  const results = [];
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...collectMapFiles(fullPath));
+      } else if (entry.name.endsWith(".map")) {
+        results.push(fullPath);
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+var sharedReleaseId = null;
+function remoteLoggerPlugin(options) {
+  if (!sharedReleaseId) sharedReleaseId = randomUUID();
+  const releaseId = sharedReleaseId;
+  let resolvedConfig;
+  let skip = false;
+  return {
+    name: "remote-logger-sourcemap",
+    enforce: "post",
+    config(config, { command, mode }) {
+      if (mode === "development" || command === "serve") {
+        skip = true;
+        return;
+      }
+      return {
+        define: {
+          __REMOTE_LOGGER_RELEASE__: JSON.stringify(releaseId)
+        }
+      };
+    },
+    configResolved(config) {
+      resolvedConfig = config;
+    },
+    async closeBundle() {
+      if (skip) return;
+      const outDir = resolvedConfig.build.outDir;
+      const mapFiles = collectMapFiles(outDir);
+      if (mapFiles.length === 0) {
+        console.log("[RemoteLogger] No source map files found, skipping upload");
+        return;
+      }
+      const endpoint = options._endpoint || DEFAULT_ENDPOINT;
+      const url = `${endpoint}/sourcemaps/upload`;
+      const formData = new FormData();
+      formData.append("releaseId", releaseId);
+      formData.append("logFileId", options.logFileId);
+      for (const mapFile of mapFiles) {
+        const content = readFileSync(mapFile);
+        const name = relative(outDir, mapFile).replace(/\\/g, "/").replace(/\//g, "_");
+        const blob = new Blob([content], { type: "application/json" });
+        formData.append("files", blob, name.endsWith(".map") ? name : `${name}.map`);
+      }
+      try {
+        console.log(`[RemoteLogger] Uploading ${mapFiles.length} source maps (release: ${releaseId})...`);
+        const response = await fetch(url, {
+          method: "POST",
+          headers: {
+            "Authorization": `Bearer ${options.apiKey}`
+          },
+          body: formData
+        });
+        if (!response.ok) {
+          const body = await response.text();
+          console.error(`[RemoteLogger] Source map upload failed (${response.status}): ${body}`);
+          return;
+        }
+        const result = await response.json();
+        console.log(`[RemoteLogger] Uploaded ${result.count} source maps successfully`);
+      } catch (err) {
+        console.error("[RemoteLogger] Source map upload failed:", err);
+      }
+    }
+  };
+}
+export {
+  remoteLoggerPlugin as default
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remote-logger/sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "JavaScript SDK for Remote Logger",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -10,6 +10,11 @@
       "types": "./dist/index.d.ts",
       "require": "./dist/index.js",
       "import": "./dist/index.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "require": "./dist/vite.js",
+      "import": "./dist/vite.mjs"
     }
   },
   "bin": {
@@ -20,7 +25,7 @@
     "SKILL.md"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts && tsup src/init.ts --format cjs --no-dts",
+    "build": "tsup src/index.ts src/vite.ts --format cjs,esm --dts && tsup src/init.ts --format cjs --no-dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "tsx test/test.ts"
   },
@@ -28,7 +33,16 @@
     "serialize-error": "^13.0.1",
     "tsup": "^8.0.0",
     "tsx": "^4.7.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vite": "^7.3.1"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
   },
   "keywords": [
     "logging",