@remote-logger/sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,522 @@
+// src/index.ts
+var LEVEL_ORDER = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  FATAL: 4
+};
+var SDK_VERSION = "0.1.0";
+var DEFAULT_BASE_URL = "https://log.terodato.com";
+var BATCH_SIZE = 50;
+var MAX_BUFFER_SIZE = 1e3;
+var FLUSH_INTERVAL_MS = 1e3;
+var FETCH_TIMEOUT_MS = 1e4;
+var batchCounter = 0;
+var generateBatchId = () => `${Date.now()}-${++batchCounter}`;
+var originalConsole = {
+  log: console.log.bind(console),
+  info: console.info.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console)
+};
+function resolveLevel(level) {
+  if (!level) return "DEBUG";
+  if (level in LEVEL_ORDER) return level;
+  return "INFO";
+}
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    const seen = /* @__PURE__ */ new WeakSet();
+    return JSON.stringify(value, (_key, val) => {
+      if (typeof val === "object" && val !== null) {
+        if (seen.has(val)) return "[Circular]";
+        seen.add(val);
+      }
+      return val;
+    });
+  }
+}
+var _Logger = class _Logger {
+  constructor(config) {
+    this.buffer = [];
+    this.flushTimer = null;
+    this.flushPromise = null;
+    this.consoleIntercepted = false;
+    this.httpBackoffMs = 0;
+    this.maxBackoffMs = 6e4;
+    this.consecutiveHttpFailures = 0;
+    // Error capture via window event listeners (no console.error wrapping to
+    // avoid polluting stack traces shown in Next.js / React error overlays)
+    this._onError = null;
+    this._onUnhandledRejection = null;
+    // WebSocket state
+    this.ws = null;
+    this.wsState = "disconnected";
+    this.wsReconnectTimer = null;
+    this.wsReconnectAttempts = 0;
+    this.maxWsReconnectAttempts = 5;
+    // Browser lifecycle hooks for best-effort flush on page unload
+    this._onVisibilityChange = null;
+    this._onBeforeUnload = null;
+    this.config = {
+      logId: config.logId,
+      apiKey: config.apiKey,
+      group: config.group,
+      level: resolveLevel(config.level),
+      onError: config.onError,
+      traceId: config.traceId,
+      silent: config.silent ?? false,
+      debug: config.debug ?? false
+    };
+    this.proxyMode = !!config._ingestUrl;
+    const baseUrl = config._endpoint ?? DEFAULT_BASE_URL;
+    this.baseUrl = baseUrl;
+    const wsBaseUrl = config._wsEndpoint ?? baseUrl;
+    this.httpIngestUrl = config._ingestUrl ?? `${baseUrl}/ingest/http`;
+    this.wsIngestUrl = `${wsBaseUrl.replace(/^http/, "ws")}/ingest/ws`;
+    this.startFlushTimer();
+    if (!this.proxyMode && typeof WebSocket !== "undefined") {
+      this.connectWebSocket();
+    } else if (this.proxyMode) {
+      this.debugLog("Proxy mode enabled, using HTTP transport only");
+    } else {
+      this.debugLog("WebSocket not available, using HTTP transport only");
+    }
+    this.registerLifecycleHooks();
+  }
+  debugLog(msg, ...args) {
+    if (this.config.debug) {
+      originalConsole.debug("[RemoteLogger]", msg, ...args);
+    }
+  }
+  connectWebSocket() {
+    if (this.wsState === "connecting" || this.wsState === "connected") {
+      return;
+    }
+    this.wsState = "connecting";
+    this.debugLog("WebSocket connecting to", this.wsIngestUrl);
+    try {
+      this.ws = new WebSocket(this.wsIngestUrl, ["api_key", this.config.apiKey]);
+      this.ws.onopen = () => {
+        this.wsReconnectAttempts = 0;
+        this.wsState = "connected";
+        this.debugLog("WebSocket connected");
+      };
+      this.ws.onmessage = (event) => {
+        try {
+          const msg = JSON.parse(event.data);
+          if (!msg.success) {
+            originalConsole.error("[RemoteLogger] WebSocket log ingestion failed:", msg.error);
+          }
+        } catch {
+        }
+      };
+      this.ws.onerror = () => {
+      };
+      this.ws.onclose = () => {
+        this.wsState = "disconnected";
+        this.ws = null;
+        if (this.wsReconnectAttempts < this.maxWsReconnectAttempts) {
+          const delay = Math.min(1e3 * Math.pow(2, this.wsReconnectAttempts), 3e4);
+          this.wsReconnectAttempts++;
+          this.debugLog(`WebSocket disconnected, reconnecting in ${delay}ms (attempt ${this.wsReconnectAttempts}/${this.maxWsReconnectAttempts})`);
+          this.wsReconnectTimer = setTimeout(() => this.connectWebSocket(), delay);
+        } else {
+          this.debugLog("WebSocket max reconnect attempts reached, using HTTP only");
+        }
+      };
+    } catch {
+      this.wsState = "failed";
+      this.debugLog("WebSocket connection failed");
+    }
+  }
+  startFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+    }
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, FLUSH_INTERVAL_MS);
+  }
+  shouldLog(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[this.config.level];
+  }
+  formatArgs(args) {
+    return args.map((arg) => {
+      if (typeof arg === "string") return arg;
+      if (arg instanceof Error) return `${arg.message}
+${arg.stack}`;
+      try {
+        return JSON.stringify(arg, null, 2);
+      } catch {
+        return String(arg);
+      }
+    }).join(" ");
+  }
+  log(level, message, options) {
+    if (!this.shouldLog(level)) return;
+    if (!this.config.silent) {
+      const method = _Logger.CONSOLE_METHOD[level];
+      const consoleArgs = [message];
+      if (options?.metadata && Object.keys(options.metadata).length > 0) {
+        consoleArgs.push(options.metadata);
+      }
+      if (options?.stack) {
+        consoleArgs.push("\n" + options.stack);
+      }
+      originalConsole[method](...consoleArgs);
+    }
+    const entry = {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      level,
+      message,
+      logId: this.config.logId,
+      group: options?.group ?? this.config.group,
+      trace_id: options?.traceId ?? this.config.traceId,
+      stack: options?.stack,
+      error_type: options?.errorType,
+      metadata: options?.metadata
+    };
+    this.buffer.push(entry);
+    if (this.buffer.length > MAX_BUFFER_SIZE) {
+      const dropped = this.buffer.length - MAX_BUFFER_SIZE;
+      this.buffer.splice(0, dropped);
+      this.debugLog(`Buffer full, dropped ${dropped} oldest logs`);
+    }
+    if (this.buffer.length >= BATCH_SIZE) {
+      this.flush();
+    }
+  }
+  parseArgs(msgOrObj, metadata) {
+    if (typeof msgOrObj === "object") {
+      return {
+        message: msgOrObj.message,
+        options: { traceId: msgOrObj.traceId, group: msgOrObj.group, metadata: msgOrObj.metadata }
+      };
+    }
+    if (metadata !== void 0) {
+      return { message: msgOrObj, options: { metadata } };
+    }
+    return { message: msgOrObj };
+  }
+  debug(msgOrObj, metadata) {
+    const { message, options } = this.parseArgs(msgOrObj, metadata);
+    this.log("DEBUG", message, options);
+  }
+  info(msgOrObj, metadata) {
+    const { message, options } = this.parseArgs(msgOrObj, metadata);
+    this.log("INFO", message, options);
+  }
+  warn(msgOrObj, metadata) {
+    const { message, options } = this.parseArgs(msgOrObj, metadata);
+    this.log("WARN", message, options);
+  }
+  error(msgOrObj, metadata) {
+    if (msgOrObj instanceof Error) {
+      this.log("ERROR", msgOrObj.message, {
+        metadata,
+        stack: msgOrObj.stack,
+        errorType: msgOrObj.name
+      });
+      return;
+    }
+    const { message, options } = this.parseArgs(msgOrObj, metadata);
+    this.log("ERROR", message, options);
+  }
+  fatal(msgOrObj, metadata) {
+    if (msgOrObj instanceof Error) {
+      this.log("FATAL", msgOrObj.message, {
+        metadata,
+        stack: msgOrObj.stack,
+        errorType: msgOrObj.name
+      });
+      return;
+    }
+    const { message, options } = this.parseArgs(msgOrObj, metadata);
+    this.log("FATAL", message, options);
+  }
+  withTraceId(traceId) {
+    return new TraceLogger(this, traceId);
+  }
+  withGroup(group) {
+    return new GroupLogger(this, group);
+  }
+  setTraceId(traceId) {
+    this.config.traceId = traceId;
+  }
+  setGroup(group) {
+    this.config.group = group;
+  }
+  interceptConsole(group) {
+    if (this.consoleIntercepted) return;
+    this.consoleIntercepted = true;
+    const self = this;
+    const logGroup = group ?? "console";
+    const wrap = (original, level) => {
+      const wrapped = (...args) => {
+        queueMicrotask(() => {
+          self.log(level, self.formatArgs(args), { group: logGroup });
+        });
+        return original.apply(console, args);
+      };
+      Object.defineProperty(wrapped, "name", { value: original.name });
+      return wrapped;
+    };
+    console.debug = wrap(originalConsole.debug, "DEBUG");
+    console.log = wrap(originalConsole.log, "INFO");
+    console.info = wrap(originalConsole.info, "INFO");
+    console.warn = wrap(originalConsole.warn, "WARN");
+    if (typeof window !== "undefined") {
+      this._onError = (event) => {
+        self.log("ERROR", event.message, {
+          group: logGroup,
+          stack: event.error?.stack,
+          errorType: event.error?.name
+        });
+      };
+      this._onUnhandledRejection = (event) => {
+        const err = event.reason;
+        const message = err instanceof Error ? err.message : String(err);
+        self.log("ERROR", message, {
+          group: logGroup,
+          stack: err instanceof Error ? err.stack : void 0,
+          errorType: err instanceof Error ? err.name : "UnhandledRejection"
+        });
+      };
+      window.addEventListener("error", this._onError);
+      window.addEventListener("unhandledrejection", this._onUnhandledRejection);
+    }
+  }
+  restoreConsole() {
+    if (!this.consoleIntercepted) return;
+    this.consoleIntercepted = false;
+    console.debug = originalConsole.debug;
+    console.log = originalConsole.log;
+    console.info = originalConsole.info;
+    console.warn = originalConsole.warn;
+    if (typeof window !== "undefined") {
+      if (this._onError) {
+        window.removeEventListener("error", this._onError);
+        this._onError = null;
+      }
+      if (this._onUnhandledRejection) {
+        window.removeEventListener("unhandledrejection", this._onUnhandledRejection);
+        this._onUnhandledRejection = null;
+      }
+    }
+  }
+  async flush() {
+    if (this.flushPromise) {
+      await this.flushPromise;
+    }
+    if (this.buffer.length === 0) return;
+    const logs = this.buffer.splice(0, this.buffer.length);
+    this.flushPromise = this.doFlush(logs);
+    try {
+      await this.flushPromise;
+    } finally {
+      this.flushPromise = null;
+    }
+  }
+  async doFlush(logs) {
+    const batchId = generateBatchId();
+    if (this.wsState === "connected" && typeof WebSocket !== "undefined") {
+      const sent = this.sendViaWebSocket(logs, batchId);
+      if (sent) return;
+    }
+    await this.sendViaHttp(logs, batchId);
+  }
+  sendViaWebSocket(logs, batchId) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return false;
+    }
+    try {
+      this.ws.send(safeStringify({ type: "logs", batchId, logs }));
+      this.debugLog(`Flushed ${logs.length} logs via WebSocket (batch ${batchId})`);
+      return true;
+    } catch {
+      this.debugLog("WebSocket send failed, falling back to HTTP");
+      return false;
+    }
+  }
+  async sendViaHttp(logs, batchId) {
+    if (this.httpBackoffMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, this.httpBackoffMs));
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const headers = {
+        "Content-Type": "application/json",
+        "X-Batch-Id": batchId,
+        "X-SDK-Version": SDK_VERSION
+      };
+      if (this.config.apiKey) {
+        headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+      }
+      const response = await fetch(this.httpIngestUrl, {
+        method: "POST",
+        headers,
+        body: safeStringify(logs),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({ error: "Unknown error" }));
+        throw new Error(error.error || `HTTP ${response.status}`);
+      }
+      this.httpBackoffMs = 0;
+      this.consecutiveHttpFailures = 0;
+      this.debugLog(`Flushed ${logs.length} logs via HTTP (batch ${batchId})`);
+    } catch (err) {
+      this.buffer.unshift(...logs);
+      this.consecutiveHttpFailures++;
+      this.httpBackoffMs = Math.min(
+        Math.pow(2, this.consecutiveHttpFailures - 1) * 1e3,
+        this.maxBackoffMs
+      );
+      this.debugLog(`HTTP flush failed (retry in ${this.httpBackoffMs / 1e3}s):`, err);
+      if (this.config.onError) {
+        this.config.onError(err, logs);
+      } else {
+        originalConsole.error(
+          `[RemoteLogger] Failed to flush logs (retry in ${this.httpBackoffMs / 1e3}s):`,
+          err
+        );
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /** Fire-and-forget flush using fetch with keepalive (works during page unload) */
+  flushSync() {
+    if (this.buffer.length === 0) return;
+    const logs = this.buffer.splice(0, this.buffer.length);
+    try {
+      const headers = {
+        "Content-Type": "application/json",
+        "X-Batch-Id": generateBatchId(),
+        "X-SDK-Version": SDK_VERSION
+      };
+      if (this.config.apiKey) {
+        headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+      }
+      fetch(this.httpIngestUrl, {
+        method: "POST",
+        headers,
+        body: safeStringify(logs),
+        keepalive: true
+      });
+    } catch {
+    }
+  }
+  registerLifecycleHooks() {
+    if (typeof window !== "undefined") {
+      this._onVisibilityChange = () => {
+        if (document.visibilityState === "hidden") {
+          this.flushSync();
+        }
+      };
+      document.addEventListener("visibilitychange", this._onVisibilityChange);
+      this._onBeforeUnload = () => {
+        this.flushSync();
+      };
+      window.addEventListener("beforeunload", this._onBeforeUnload);
+    }
+  }
+  /** Check server connectivity and API key validity */
+  async ping() {
+    const start = Date.now();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const headers = {};
+      if (this.config.apiKey) {
+        headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+      }
+      const response = await fetch(`${this.baseUrl}/health`, {
+        headers,
+        signal: controller.signal
+      });
+      const latencyMs = Date.now() - start;
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({ error: `HTTP ${response.status}` }));
+        return { ok: false, latencyMs, error: body.error || `HTTP ${response.status}` };
+      }
+      return { ok: true, latencyMs };
+    } catch (err) {
+      return { ok: false, latencyMs: Date.now() - start, error: err.message };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  /** Get current connection status */
+  getConnectionStatus() {
+    if (this.wsState === "connected") {
+      return { transport: "websocket", state: "connected" };
+    }
+    return { transport: "http", state: "connected" };
+  }
+};
+_Logger.CONSOLE_METHOD = {
+  DEBUG: "debug",
+  INFO: "info",
+  WARN: "warn",
+  ERROR: "error",
+  FATAL: "error"
+};
+var Logger = _Logger;
+var TraceLogger = class {
+  constructor(parent, traceId) {
+    this.parent = parent;
+    this.traceId = traceId;
+  }
+  debug(message, metadata) {
+    this.parent.debug({ message, traceId: this.traceId, metadata });
+  }
+  info(message, metadata) {
+    this.parent.info({ message, traceId: this.traceId, metadata });
+  }
+  warn(message, metadata) {
+    this.parent.warn({ message, traceId: this.traceId, metadata });
+  }
+  error(message, metadata) {
+    this.parent.error({ message, traceId: this.traceId, metadata });
+  }
+  fatal(message, metadata) {
+    this.parent.fatal({ message, traceId: this.traceId, metadata });
+  }
+};
+var GroupLogger = class {
+  constructor(parent, group) {
+    this.parent = parent;
+    this.group = group;
+  }
+  debug(message, metadata) {
+    this.parent.debug({ message, group: this.group, metadata });
+  }
+  info(message, metadata) {
+    this.parent.info({ message, group: this.group, metadata });
+  }
+  warn(message, metadata) {
+    this.parent.warn({ message, group: this.group, metadata });
+  }
+  error(message, metadata) {
+    this.parent.error({ message, group: this.group, metadata });
+  }
+  fatal(message, metadata) {
+    this.parent.fatal({ message, group: this.group, metadata });
+  }
+};
+function createLogger(config) {
+  return new Logger(config);
+}
+var index_default = createLogger;
+export {
+  Logger,
+  createLogger,
+  index_default as default
+};

package/dist/init.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/init.ts
+var import_fs = require("fs");
+var import_path = require("path");
+var CLAUDE_MD = "CLAUDE.md";
+var CURSORRULES = ".cursorrules";
+var SKILL_REF = "> See node_modules/@remote-logger/sdk/SKILL.md for the @remote-logger/sdk logging workflow.";
+var cwd = process.cwd();
+function appendIfMissing(filename) {
+  const filepath = (0, import_path.resolve)(cwd, filename);
+  const marker = "node_modules/@remote-logger/sdk/SKILL.md";
+  let content = "";
+  if ((0, import_fs.existsSync)(filepath)) {
+    content = (0, import_fs.readFileSync)(filepath, "utf-8");
+    if (content.includes(marker)) {
+      console.log(`  ${filename}: already configured, skipping`);
+      return false;
+    }
+  }
+  const separator = content.length > 0 && !content.endsWith("\n") ? "\n\n" : content.length > 0 ? "\n" : "";
+  (0, import_fs.writeFileSync)(filepath, content + separator + SKILL_REF + "\n", "utf-8");
+  console.log(`  ${filename}: ${content.length > 0 ? "updated" : "created"}`);
+  return true;
+}
+console.log("\n@remote-logger/sdk init\n");
+var claudeUpdated = appendIfMissing(CLAUDE_MD);
+var cursorUpdated = appendIfMissing(CURSORRULES);
+if (!claudeUpdated && !cursorUpdated) {
+  console.log("\nAlready set up \u2014 nothing to do.\n");
+} else {
+  console.log("\nDone. Your AI assistant now has access to the Remote Logger workflow guide.\n");
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@remote-logger/sdk",
+  "version": "0.1.0",
+  "description": "JavaScript SDK for Remote Logger",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "bin": {
+    "remote-logger-init": "dist/init.js"
+  },
+  "files": [
+    "dist",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.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"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "logging",
+    "remote-logger",
+    "observability"
+  ],
+  "license": "MIT"
+}